Public Modules and Classes

Note

Only public classes and methods interesting to pyfakefs users are shown. Methods that mimic the behavior of standard Python functions and classes that are only needed internally are not listed.

Fake filesystem module

Helper classes use for fake file system implementation.

pyfakefs.helpers.get_uid() int

Get the global user id. Same as os.getuid()

pyfakefs.helpers.set_uid(uid: int) None

Set the global user id. This is used as st_uid for new files and to differentiate between a normal user and the root user (uid 0). For the root user, some permission restrictions are ignored.

Parameters:

uid – (int) the user ID of the user calling the file system functions.

pyfakefs.helpers.get_gid() int

Get the global group id. Same as os.getgid()

pyfakefs.helpers.set_gid(gid: int) None

Set the global group id. This is only used to set st_gid for new files, no permission checks are performed.

Parameters:

gid – (int) the group ID of the user calling the file system functions.

pyfakefs.helpers.reset_ids() None

Set the global user ID and group ID back to default values.

pyfakefs.helpers.is_root() bool

Return True if the current user is the root user.

Fake filesystem classes

class pyfakefs.fake_filesystem.FakeFilesystem(path_separator: str = '/', total_size: int | None = None, patcher: Any = None, create_temp_dir: bool = False)

Provides the appearance of a real directory tree for unit testing.

path_separator

The path separator, corresponds to os.path.sep.

alternative_path_separator

Corresponds to os.path.altsep.

is_windows_fs

True in a real or faked Windows file system.

is_macos

True under MacOS, or if we are faking it.

is_case_sensitive

True if a case-sensitive file system is assumed.

root

The root FakeDirectory entry of the file system.

umask

The umask used for newly created files, see os.umask.

patcher

Holds the Patcher object if created from it. Allows access to the patcher object if using the pytest fs fixture.

patch_open_code

Defines how io.open_code will be patched; patching can be on, off, or in automatic mode.

shuffle_listdir_results

If True, os.listdir will not sort the results to match the real file system behavior.

Parameters:
  • path_separator – optional substitute for os.path.sep

  • total_size – if not None, the total size in bytes of the root filesystem.

  • patcher – the Patcher instance if created from the Patcher

  • create_temp_dir – If True, a temp directory is created on initialization. Under Posix, if the temp directory is not /tmp, a link to the temp path is additionally created at /tmp.

Example usage to use the same path separator under all systems:

>>> filesystem = FakeFilesystem(path_separator='/')
pause() None

Pause the patching of the file system modules until resume() is called. After that call, all file system calls are executed in the real file system. Calling pause() twice is silently ignored. Only allowed if the file system object was created by a Patcher object. This is also the case for the pytest fs fixture.

Raises:

RuntimeError – if the file system was not created by a Patcher.

resume() None

Resume the patching of the file system modules if pause() has been called before. After that call, all file system calls are executed in the fake file system. Does nothing if patching is not paused. :raises RuntimeError: if the file system has not been created by Patcher.

add_mount_point(path: AnyStr, total_size: int | None = None, can_exist: bool = False) Dict

Add a new mount point for a filesystem device. The mount point gets a new unique device number.

Parameters:
  • path – The root path for the new mount path.

  • total_size – The new total size of the added filesystem device in bytes. Defaults to infinite size.

  • can_exist – If True, no error is raised if the mount point already exists.

Returns:

The newly created mount point dict.

Raises:

OSError – if trying to mount an existing mount point again, and can_exist is False.

get_disk_usage(path: AnyStr | None = None) Tuple[int, int, int]

Return the total, used and free disk space in bytes as named tuple, or placeholder values simulating unlimited space if not set.

Note

This matches the return value of shutil.disk_usage().

Parameters:

path – The disk space is returned for the file system device where path resides. Defaults to the root path (e.g. ‘/’ on Unix systems).

set_disk_usage(total_size: int, path: AnyStr | None = None) None

Changes the total size of the file system, preserving the used space. Example usage: set the size of an auto-mounted Windows drive.

Parameters:
  • total_size – The new total size of the filesystem in bytes.

  • path – The disk space is changed for the file system device where path resides. Defaults to the root path (e.g. ‘/’ on Unix systems).

Raises:

OSError – if the new space is smaller than the used size.

change_disk_usage(usage_change: int, file_path: AnyStr, st_dev: int) None

Change the used disk space by the given amount.

Parameters:
  • usage_change – Number of bytes added to the used space. If negative, the used space will be decreased.

  • file_path – The path of the object needing the disk space.

  • st_dev – The device ID for the respective file system.

Raises:

OSError – if usage_change exceeds the free file system space

get_object(file_path: AnyStr | PathLike, check_read_perm: bool = True) FakeFile

Search for the specified filesystem object within the fake filesystem.

Parameters:
  • file_path – Specifies the target FakeFile object to retrieve.

  • check_read_perm – If True, raises OSError if a parent directory does not have read permission

Returns:

The FakeFile object corresponding to file_path.

Raises:

OSError – if the object is not found.

create_dir(directory_path: AnyStr | PathLike, perm_bits: int = 511) FakeDirectory

Create directory_path and all the parent directories, and return the created FakeDirectory object.

Helper method to set up your test faster.

Parameters:
  • directory_path – The full directory path to create.

  • perm_bits – The permission bits as set by chmod.

Returns:

The newly created FakeDirectory object.

Raises:

OSError – if the directory already exists.

create_file(file_path: AnyStr | PathLike, st_mode: int = 33206, contents: str | bytes = '', st_size: int | None = None, create_missing_dirs: bool = True, apply_umask: bool = True, encoding: str | None = None, errors: str | None = None, side_effect: Callable | None = None) FakeFile

Create file_path, including all the parent directories along the way, and return the created FakeFile object.

This helper method can be used to set up tests more easily.

Parameters:
  • file_path – The path to the file to create.

  • st_mode – The stat constant representing the file type.

  • contents – the contents of the file. If not given and st_size is None, an empty file is assumed.

  • st_size – file size; only valid if contents not given. If given, the file is considered to be in “large file mode” and trying to read from or write to the file will result in an exception.

  • create_missing_dirs – If True, auto create missing directories.

  • apply_umaskTrue if the current umask must be applied on st_mode.

  • encoding – If contents is of type str, the encoding used for serialization.

  • errors – The error mode used for encoding/decoding errors.

  • side_effect – function handle that is executed when the file is written, must accept the file object as an argument.

Returns:

The newly created FakeFile object.

Raises:
  • OSError – if the file already exists.

  • OSError – if the containing directory is required and missing.

add_real_file(source_path: AnyStr | PathLike, read_only: bool = True, target_path: AnyStr | PathLike | None = None) FakeFile

Create file_path, including all the parent directories along the way, for an existing real file, and return the created FakeFile object. The contents of the real file are read only on demand.

Parameters:
  • source_path – Path to an existing file in the real file system

  • read_only – If True (the default), writing to the fake file raises an exception. Otherwise, writing to the file changes the fake file only.

  • target_path – If given, the path of the target direction, otherwise it is equal to source_path.

Returns:

the newly created FakeFile object.

Raises:
  • OSError – if the file does not exist in the real file system.

  • OSError – if the file already exists in the fake file system.

Note

On most systems, accessing the fake file’s contents may update both the real and fake files’ atime (access time). In this particular case, add_real_file() violates the rule that pyfakefs must not modify the real file system.

Create a symlink at source_path (or target_path, if given) and return the created FakeFile object. It will point to the same path as the symlink on the real filesystem. Relative symlinks will point relative to their new location. Absolute symlinks will point to the same, absolute path as on the real filesystem.

Parameters:
  • source_path – The path to the existing symlink.

  • target_path – If given, the name of the symlink in the fake filesystem, otherwise, the same as source_path.

Returns:

the newly created FakeFile object.

Raises:
  • OSError – if the directory does not exist in the real file system.

  • OSError – if the symlink could not be created (see create_file()).

  • OSError – if the directory already exists in the fake file system.

add_real_directory(source_path: AnyStr | PathLike, read_only: bool = True, lazy_read: bool = True, target_path: AnyStr | PathLike | None = None) FakeDirectory

Create a fake directory corresponding to the real directory at the specified path, and return the created FakeDirectory object. Add entries in the fake directory corresponding to the entries in the real directory. Symlinks are supported. If the target directory already exists in the fake filesystem, the directory contents are merged. Overwriting existing files is not allowed.

Parameters:
  • source_path – The path to the existing directory.

  • read_only – If set, all files under the directory are treated as read-only, e.g. a write access raises an exception; otherwise, writing to the files changes the fake files only as usually.

  • lazy_read

    If set (default), directory contents are only read when accessed, and only until the needed subdirectory level.

    Note

    This means that the file system size is only updated at the time the directory contents are read; set this to False only if you are dependent on accurate file system size in your test

  • target_path – If given, the target directory, otherwise, the target directory is the same as source_path.

Returns:

the newly created FakeDirectory object.

Raises:
  • OSError – if the directory does not exist in the real filesystem.

  • OSError – if a file or link exists in the fake filesystem where a real file or directory shall be mapped.

add_real_paths(path_list: List, read_only: bool = True, lazy_dir_read: bool = True) None

This convenience method adds multiple files and/or directories from the real file system to the fake file system. See add_real_file() and add_real_directory().

Parameters:
  • path_list – List of file and directory paths in the real file system.

  • read_only – If set, all files and files under the directories are treated as read-only, e.g. a write access raises an exception; otherwise, writing to the files changes the fake files only as usually.

  • lazy_dir_read – Uses lazy reading of directory contents if set (see add_real_directory())

Raises:
  • OSError – if any of the files and directories in the list does not exist in the real file system.

  • OSError – if a file or link exists in the fake filesystem where a real file or directory shall be mapped.

Create the specified symlink, pointed at the specified link target, and return the created FakeFile object representing the link.

Parameters:
  • file_path – path to the symlink to create

  • link_target – the target of the symlink

  • create_missing_dirs – If True, any missing parent directories of file_path will be created

Returns:

The newly created FakeFile object.

Raises:

OSError – if the symlink could not be created (see create_file()).

Create a hard link at new_path, pointing at old_path, and return the created FakeFile object representing the link.

Parameters:
  • old_path – An existing link to the target file.

  • new_path – The destination path to create a new link at.

  • follow_symlinks – If False and old_path is a symlink, link the symlink instead of the object it points to.

  • create_missing_dirs – If True, any missing parent directories of file_path will be created

Returns:

The FakeFile object referred to by old_path.

Raises:
  • OSError – if something already exists at new_path.

  • OSError – if old_path is a directory.

  • OSError – if the parent directory doesn’t exist.

class pyfakefs.fake_file.FakeFile(name: AnyStr, st_mode: int = 33206, contents: AnyStr | None = None, filesystem: FakeFilesystem | None = None, encoding: str | None = None, errors: str | None = None, side_effect: Callable[[FakeFile], None] | None = None, open_modes: _OpenModes | None = None)

Provides the appearance of a real file.

Attributes currently faked out:
  • st_mode: user-specified, otherwise S_IFREG

  • st_ctime: the time.time() timestamp of the file change time (updated each time a file’s attributes is modified).

  • st_atime: the time.time() timestamp when the file was last accessed.

  • st_mtime: the time.time() timestamp when the file was last modified.

  • st_size: the size of the file

  • st_nlink: the number of hard links to the file

  • st_ino: the inode number - a unique number identifying the file

  • st_dev: a unique number identifying the (fake) file system device the file belongs to

  • st_uid: always set to USER_ID, which can be changed globally using

    set_uid

  • st_gid: always set to GROUP_ID, which can be changed globally using

    set_gid

Note

The resolution for st_ctime, st_mtime and st_atime in the real file system depends on the used file system (for example it is only 1s for HFS+ and older Linux file systems, but much higher for ext4 and NTFS). This is currently ignored by pyfakefs, which uses the resolution of time.time().

Under Windows, st_atime is not updated for performance reasons by default. pyfakefs never updates st_atime under Windows, assuming the default setting.

Parameters:
  • name – Name of the file/directory, without parent path information

  • st_mode – The stat.S_IF* constant representing the file type (i.e. stat.S_IFREG, stat.S_IFDIR), and the file permissions. If no file type is set (e.g. permission flags only), a regular file type is assumed.

  • contents – The contents of the filesystem object; should be a string or byte object for regular files, and a dict of other FakeFile or FakeDirectory objects with the file names as keys for FakeDirectory objects

  • filesystem – The fake filesystem where the file is created.

  • encoding – If contents is a unicode string, the encoding used for serialization.

  • errors – The error mode used for encoding/decoding errors.

  • side_effect – function handle that is executed when file is written, must accept the file object as an argument.

  • open_modes – The modes the file was opened with (e.g. can read, write etc.)

property byte_contents: bytes | None

Return the contents as raw byte array.

property contents: str | None

Return the contents as string with the original encoding.

is_large_file() bool

Return True if this file was initialized with size but no contents.

set_contents(contents: AnyStr, encoding: str | None = None) bool

Sets the file contents and size and increases the modification time. Also executes the side_effects if available.

Parameters:
  • contents – (str, bytes) new content of file.

  • encoding – (str) the encoding to be used for writing the contents if they are a unicode string. If not given, the locale preferred encoding is used.

Returns:

True if the contents have been changed.

Raises:

OSError – if st_size is not a non-negative integer, or if it exceeds the available file system space.

property size: int

Return the size in bytes of the file contents.

property path: AnyStr

Return the full path of the current object.

class pyfakefs.fake_file.FakeDirectory(name: str, perm_bits: int = 511, filesystem: FakeFilesystem | None = None)

Provides the appearance of a real directory.

Parameters:
  • name – name of the file/directory, without parent path information

  • perm_bits – permission bits. defaults to 0o777.

  • filesystem – if set, the fake filesystem where the directory is created

property ordered_dirs: List[str]

Return the list of contained directory entry names ordered by creation order.

get_entry(pathname_name: str) FakeFile | FakeDirectory

Retrieves the specified child file or directory entry.

Parameters:

pathname_name – The basename of the child object to retrieve.

Returns:

The fake file or directory object.

Raises:

KeyError – if no child exists by the specified name.

remove_entry(pathname_name: str, recursive: bool = True) None

Removes the specified child file or directory.

Parameters:
  • pathname_name – Basename of the child object to remove.

  • recursive – If True (default), the entries in contained directories are deleted first. Used to propagate removal errors (e.g. permission problems) from contained entries.

Raises:
  • KeyError – if no child exists by the specified name.

  • OSError – if user lacks permission to delete the file, or (Windows only) the file is open.

property size: int

Return the total size of all files contained in this directory tree.

property contents: str | None

Return the contents as string with the original encoding.

Unittest module classes

class pyfakefs.fake_filesystem_unittest.TestCaseMixin

Test case mixin that automatically replaces file-system related modules by fake implementations.

additional_skip_names

names of modules where no module replacement shall be performed, in addition to the names in fake_filesystem_unittest.Patcher.SKIPNAMES. Instead of the module names, the modules themselves may be used.

Type:

List[str | module] | None

modules_to_reload

A list of modules that need to be reloaded to be patched dynamically; may be needed if the module imports file system modules under an alias

Caution

Reloading modules may have unwanted side effects.

Type:

List[module] | None

modules_to_patch

A dictionary of fake modules mapped to the fully qualified patched module names. Can be used to add patching of modules not provided by pyfakefs.

Type:

Dict[str, module] | None

If you specify some of these attributes here, and you have DocTests, consider also specifying the same arguments to load_doctests().

Example usage in derived test classes:

from unittest import TestCase
from fake_filesystem_unittest import TestCaseMixin

class MyTestCase(TestCase, TestCaseMixin):
    def __init__(self, methodName='runTest'):
        super(MyTestCase, self).__init__(
            methodName=methodName,
            additional_skip_names=['posixpath'])

import sut

class AnotherTestCase(TestCase, TestCaseMixin):
    def __init__(self, methodName='runTest'):
        super(MyTestCase, self).__init__(
            methodName=methodName, modules_to_reload=[sut])
setUpPyfakefs(additional_skip_names: List[str | module] | None = None, modules_to_reload: List[module] | None = None, modules_to_patch: Dict[str, module] | None = None, allow_root_user: bool = True, use_known_patches: bool = True, patch_open_code: PatchMode = PatchMode.OFF, patch_default_args: bool = False, use_cache: bool = True, use_dynamic_patch: bool = True) None

Bind the file-related modules to the pyfakefs fake file system instead of the real file system. Also bind the fake open() function.

Invoke this at the beginning of the setUp() method in your unit test class. For the arguments, see the TestCaseMixin attribute description. If any of the arguments is not None, it overwrites the settings for the current test case. Settings the arguments here may be a more convenient way to adapt the setting than overwriting __init__().

classmethod setUpClassPyfakefs(additional_skip_names: List[str | module] | None = None, modules_to_reload: List[module] | None = None, modules_to_patch: Dict[str, module] | None = None, allow_root_user: bool = True, use_known_patches: bool = True, patch_open_code: PatchMode = PatchMode.OFF, patch_default_args: bool = False, use_cache: bool = True, use_dynamic_patch: bool = True) None

Similar to setUpPyfakefs(), but as a class method that can be used in setUpClass instead of in setUp. The fake filesystem will live in all test methods in the test class and can be used in the usual way. Note that using both setUpClassPyfakefs() and setUpPyfakefs() in the same class will not work correctly.

Note

This method is only available from Python 3.8 onwards.

Note

If using pytest as testrunner, you need at least pytest 6.2 for this method to work.

pause() None

Pause the patching of the file system modules until resume is called. After that call, all file system calls are executed in the real file system. Calling pause() twice is silently ignored.

resume() None

Resume the patching of the file system modules if pause has been called before. After that call, all file system calls are executed in the fake file system. Does nothing if patching is not paused.

class pyfakefs.fake_filesystem_unittest.TestCase(methodName: str = 'runTest', additional_skip_names: List[str | module] | None = None, modules_to_reload: List[module] | None = None, modules_to_patch: Dict[str, module] | None = None)

Test case class that automatically replaces file-system related modules by fake implementations. Inherits TestCaseMixin.

The arguments are explained in TestCaseMixin.

Creates the test class instance and the patcher used to stub out file system related modules.

Parameters:

methodName – The name of the test method (same as in unittest.TestCase)

class pyfakefs.fake_filesystem_unittest.Patcher(*args, **kwargs)

Instantiate a stub creator to bind and un-bind the file-related modules to the pyfakefs fake modules.

The arguments are explained in TestCaseMixin.

Patcher is used in TestCaseMixin. Patcher also works as a context manager for other tests:

with Patcher():
    doStuff()
Parameters:
  • additional_skip_names – names of modules where no module replacement shall be performed, in addition to the names in fake_filesystem_unittest.Patcher.SKIPNAMES. Instead of the module names, the modules themselves may be used.

  • modules_to_reload

    A list of modules that need to be reloaded to be patched dynamically; may be needed if the module imports file system modules under an alias

    Caution

    Reloading modules may have unwanted side effects.

  • modules_to_patch – A dictionary of fake modules mapped to the fully qualified patched module names. Can be used to add patching of modules not provided by pyfakefs.

  • allow_root_user – If True (default), if the test is run as root user, the user in the fake file system is also considered a root user, otherwise it is always considered a regular user.

  • use_known_patches – If True (the default), some patches for commonly used packages are applied which make them usable with pyfakefs.

  • patch_open_code – If True, io.open_code is patched. The default is not to patch it, as it mostly is used to load compiled modules that are not in the fake file system.

  • patch_default_args – If True, default arguments are checked for file system functions, which are patched. This check is expansive, so it is off by default.

  • use_cache – If True (default), patched and non-patched modules are cached between tests for performance reasons. As this is a new feature, this argument allows to turn it off in case it causes any problems.

  • use_dynamic_patch – If True, dynamic patching after setup is used (for example for modules loaded locally inside of functions). Can be switched off if it causes unwanted side effects.

register_cleanup_handler(name: str, handler: Callable[[str], bool])

Register a handler for cleaning up a module after it had been loaded by the dynamic patcher. This allows to handle modules that cannot be reloaded without unwanted side effects.

Parameters:
  • name – The fully qualified module name.

  • handler – A callable that may do any module cleanup, or do nothing and return True in case reloading shall be prevented.

Returns:

True if no further cleanup/reload shall occur after the handler is

executed, False if the cleanup/reload shall still happen.

setUp(doctester: Any = None) None

Bind the file-related modules to the pyfakefs fake modules real ones. Also bind the fake file() and open() functions.

tearDown(doctester: Any = None)

Clear the fake filesystem bindings created by setUp().

pause() None

Pause the patching of the file system modules until resume is called. After that call, all file system calls are executed in the real file system. Calling pause() twice is silently ignored.

resume() None

Resume the patching of the file system modules if pause has been called before. After that call, all file system calls are executed in the fake file system. Does nothing if patching is not paused.

This module provides a base class derived from unittest.TestClass for unit tests using the pyfakefs module.

fake_filesystem_unittest.TestCase searches sys.modules for modules that import the os, io, path shutil, and pathlib modules.

The setUpPyfakefs() method binds these modules to the corresponding fake modules from pyfakefs. Further, the open() built-in is bound to a fake open().

It is expected that setUpPyfakefs() be invoked at the beginning of the derived class’ setUp() method. There is no need to add anything to the derived class’ tearDown() method.

During the test, everything uses the fake file system and modules. This means that even in your test fixture, familiar functions like open() and os.makedirs() manipulate the fake file system.

Existing unit tests that use the real file system can be retrofitted to use pyfakefs by simply changing their base class from :py:class`unittest.TestCase to :py:class`pyfakefs.fake_filesystem_unittest.TestCase.

pyfakefs.fake_filesystem_unittest.patchfs(_func: Callable | None = None, *, additional_skip_names: List[str | module] | None = None, modules_to_reload: List[module] | None = None, modules_to_patch: Dict[str, module] | None = None, allow_root_user: bool = True, use_known_patches: bool = True, patch_open_code: PatchMode = PatchMode.OFF, patch_default_args: bool = False, use_cache: bool = True, use_dynamic_patch: bool = True) Callable

Convenience decorator to use patcher with additional parameters in a test function.

Usage:

@patchfs
def test_my_function(fake_fs):
    fake_fs.create_file('foo')

@patchfs(allow_root_user=False)
def test_with_patcher_args(fs):
    os.makedirs('foo/bar')

Faked module classes

class pyfakefs.fake_os.FakeOsModule(filesystem: FakeFilesystem)

Uses FakeFilesystem to provide a fake os module replacement.

Do not create os.path separately from os, as there is a necessary circular dependency between os and os.path to replicate the behavior of the standard Python modules. What you want to do is to just let FakeOsModule take care of os.path setup itself.

# You always want to do this. filesystem = fake_filesystem.FakeFilesystem() my_os_module = fake_os.FakeOsModule(filesystem)

Also exposes self.path (to fake os.path).

Parameters:

filesystem – FakeFilesystem used to provide file system information

class pyfakefs.fake_path.FakePathModule(filesystem: FakeFilesystem, os_module: FakeOsModule)

Faked os.path module replacement.

FakePathModule should only be instantiated by FakeOsModule. See the FakeOsModule docstring for details.

Init.

Parameters:

filesystem – FakeFilesystem used to provide file system information

class pyfakefs.fake_open.FakeFileOpen(filesystem: FakeFilesystem, delete_on_close: bool = False, raw_io: bool = False)

Faked file() and open() function replacements.

Returns FakeFile objects in a FakeFilesystem in place of the file() or open() function.

Parameters:
  • filesystem – FakeFilesystem used to provide file system information

  • delete_on_close – optional boolean, deletes file on close()

class pyfakefs.fake_io.FakeIoModule(filesystem: FakeFilesystem)

Uses FakeFilesystem to provide a fake io module replacement.

You need a fake_filesystem to use this: filesystem = fake_filesystem.FakeFilesystem() my_io_module = fake_io.FakeIoModule(filesystem)

Parameters:

filesystem – FakeFilesystem used to provide file system information.

class pyfakefs.fake_filesystem_shutil.FakeShutilModule(filesystem)

Uses a FakeFilesystem to provide a fake replacement for shutil module.

Construct fake shutil module using the fake filesystem.

Parameters:

filesystem – FakeFilesystem used to provide file system information

class pyfakefs.fake_pathlib.FakePathlibModule(filesystem)

Uses FakeFilesystem to provide a fake pathlib module replacement.

You need a fake_filesystem to use this: filesystem = fake_filesystem.FakeFilesystem() fake_pathlib_module = fake_filesystem.FakePathlibModule(filesystem)

Initializes the module with the given filesystem.

Parameters:

filesystem – FakeFilesystem used to provide file system information