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

A fake filesystem implementation for unit testing.

Includes
Usage

>>> from pyfakefs import fake_filesystem
>>> filesystem = fake_filesystem.FakeFilesystem()
>>> os_module = fake_filesystem.FakeOsModule(filesystem)
>>> pathname = '/a/new/dir/new-file'

Create a new file object, creating parent directory objects as needed:

>>> os_module.path.exists(pathname)
False
>>> new_file = filesystem.create_file(pathname)

File objects can’t be overwritten:

>>> os_module.path.exists(pathname)
True
>>> try:
...   filesystem.create_file(pathname)
... except OSError as e:
...   assert e.errno == errno.EEXIST, 'unexpected errno: %d' % e.errno
...   assert e.strerror == 'File exists in the fake filesystem'

Remove a file object:

>>> filesystem.remove_object(pathname)
>>> os_module.path.exists(pathname)
False

Create a new file object at the previous path:

>>> beatles_file = filesystem.create_file(pathname,
...     contents='Dear Prudence\nWon\'t you come out to play?\n')
>>> os_module.path.exists(pathname)
True

Use the FakeFileOpen class to read fake file objects:

>>> file_module = fake_filesystem.FakeFileOpen(filesystem)
>>> for line in file_module(pathname):
...     print(line.rstrip())
...
Dear Prudence
Won't you come out to play?

File objects cannot be treated like directory objects:

>>> try:
...   os_module.listdir(pathname)
... except OSError as e:
...   assert e.errno == errno.ENOTDIR, 'unexpected errno: %d' % e.errno
...   assert e.strerror == 'Not a directory in the fake filesystem'

The FakeOsModule can list fake directory objects:

>>> os_module.listdir(os_module.path.dirname(pathname))
['new-file']

The FakeOsModule also supports stat operations:

>>> import stat
>>> stat.S_ISREG(os_module.stat(pathname).st_mode)
True
>>> stat.S_ISDIR(os_module.stat(os_module.path.dirname(pathname)).st_mode)
True
pyfakefs.fake_filesystem.set_uid(uid)

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.fake_filesystem.set_gid(gid)

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

Parameters

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

Fake filesystem classes

class pyfakefs.fake_filesystem.FakeFilesystem(path_separator='\\', total_size=None, patcher=None)

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.

cwd

The current working directory path.

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.

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

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

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

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

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()

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, total_size=None)

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.

Returns

The newly created mount point dict.

Raises

OSError – if trying to mount an existing mount point again.

get_disk_usage(path=None)

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, path=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.

get_object(file_path, check_read_perm=True)

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, perm_bits=511)

Create directory_path, and all the parent directories.

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, st_mode=33206, contents='', st_size=None, create_missing_dirs=True, apply_umask=False, encoding=None, errors=None, side_effect=None)

Create file_path, including all the parent directories along the way.

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 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.

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, read_only=True, target_path=None)

Create file_path, including all the parent directories along the way, for an existing real file. 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). 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 fileystem, otherwise, the same as source_path.

Returns

the newly created FakeDirectory 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, read_only=True, lazy_read=True, target_path=None)

Create a fake directory corresponding to the real directory at the specified path. Add entries in the fake directory corresponding to the entries in the real directory. Symlinks are supported.

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 file system.

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

add_real_paths(path_list, read_only=True, lazy_dir_read=True)

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 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 any of the files and directories in the list already exists in the fake file system.

Create the specified symlink, pointed at the specified link target.

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()).

class pyfakefs.fake_filesystem.FakeFile(name, st_mode=33206, contents=None, filesystem=None, encoding=None, errors=None, side_effect=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 list of other FakeFile or FakeDirectory objects 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.

property byte_contents

Return the contents as raw byte array.

property contents

Return the contents as string with the original encoding.

is_large_file()

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

set_contents(contents, encoding=None)

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

Parameters
  • contents – (str, bytes, unicode) 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.

Raises

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

property size

Return the size in bytes of the file contents.

property path

Return the full path of the current object.

class pyfakefs.fake_filesystem.FakeDirectory(name, perm_bits=511, filesystem=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 contents

Return the list of contained directory entries.

property ordered_dirs

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

get_entry(pathname_name)

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, recursive=True)

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

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

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 inside of which 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.

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=None, modules_to_reload=None, modules_to_patch=None, allow_root_user=True, use_known_patches=True, patch_open_code=<PatchMode.OFF: 1>, patch_default_args=False, use_cache=True)

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__().

pause()

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()

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='runTest', additional_skip_names=None, modules_to_reload=None, modules_to_patch=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(additional_skip_names=None, modules_to_reload=None, modules_to_patch=None, allow_root_user=True, use_known_patches=True, patch_open_code=<PatchMode.OFF: 1>, patch_default_args=False, use_cache=True)

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 inside of which 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.

setUp(doctester=None)

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

tearDown(doctester=None)

Clear the fake filesystem bindings created by setUp().

pause()

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()

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=None, *, additional_skip_names=None, modules_to_reload=None, modules_to_patch=None, allow_root_user=True, use_known_patches=True, patch_open_code=<PatchMode.OFF: 1>, patch_default_args=False, use_cache=True)

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_filesystem.FakeOsModule(filesystem)

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_filesystem.FakeOsModule(filesystem)

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

Parameters

filesystem – FakeFilesystem used to provide file system information

class pyfakefs.fake_filesystem.FakePathModule(filesystem, os_module)

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_filesystem.FakeFileOpen(filesystem, delete_on_close=False, raw_io=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_filesystem.FakeIoModule(filesystem)

Uses FakeFilesystem to provide a fake io module replacement.

Currently only used to wrap io.open() which is an alias to open().

You need a fake_filesystem to use this: filesystem = fake_filesystem.FakeFilesystem() my_io_module = fake_filesystem.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. Can be used to replace both the standard pathlib module and the pathlib2 package available on PyPi.

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

class pyfakefs.fake_scandir.FakeScanDirModule(filesystem)

Uses FakeFilesystem to provide a fake scandir module replacement.

Note

The scandir function is a part of the standard os module since Python 3.5. This class handles the separate scandir module that is available on pypi.

You need a fake_filesystem to use this: filesystem = fake_filesystem.FakeFilesystem() fake_scandir_module = fake_filesystem.FakeScanDirModule(filesystem)