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

FakeFile: Provides the appearance of a real file.
FakeDirectory: Provides the appearance of a real directory.
FakeFilesystem: Provides the appearance of a real directory hierarchy.
FakeOsModule: Uses FakeFilesystem to provide a fake os module replacement.
FakeIoModule: Uses FakeFilesystem to provide a fake io module replacement.
FakePathModule: Faked os.path module replacement.
FakeFileOpen: Faked file() and open() function replacements.

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 IOError 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 emulate real file systems:

>>> filesystem = FakeFilesystem(
...     alt_path_separator='/' if _is_windows else None)

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

IOError – 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

IOError – 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_umask – True 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

IOError – if the file already exists.
IOError – 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.
IOError – 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.

add_real_symlink(source_path, target_path=None)¶

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 on Windows before Python 3.2.
IOError – 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.
IOError – 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_symlink(file_path, link_target, create_missing_dirs=True)¶

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()).
OSError – if on Windows before Python 3.2.

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

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

property path¶: Return the full path of the current object.

property size¶: Return the size in bytes of the file contents.

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

Bind the file-related modules to the pyfakefs fake file system instead of the real file system. Also bind the fake open() function, and on Python 2, the file() 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, allow_root_user=True)¶

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

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

For a description of the arguments, see TestCase.__init__

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.

Faked module classes¶

class pyfakefs.fake_filesystem.FakeOsModule(filesystem, os_path_module=None)¶

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
os_path_module – (deprecated) Optional FakePathModule instance

class pyfakefs.fake_filesystem.FakePathModule(filesystem, os_module=None)¶

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
os_module – (deprecated) FakeOsModule to assign to self.os

class pyfakefs.fake_filesystem.FakeFileOpen(filesystem, delete_on_close=False, use_io=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()
use_io – if True, the io.open() version is used (ignored for Python 3, where io.open() is an alias to open() )

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)

Public Modules and Classes¶

Fake filesystem module¶

Fake filesystem classes¶

Unittest module classes¶

Faked module classes¶

Table of Contents

Previous topic

Next topic

This Page