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 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
Fake filesystem classes¶
-
class
pyfakefs.fake_filesystem.
FakeFilesystem
(path_separator='/', total_size=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.
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)
-
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)¶ Search for the specified filesystem object within the fake filesystem.
Parameters: file_path – Specifies the target FakeFile object to retrieve. 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)¶ 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.
- st_size – The file size; only valid if contents not given.
- 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.
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_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.
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 (seecreate_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)¶ 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
Other attributes needed by os.stat are assigned a default value of None. These include st_uid and st_gid.
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.
-
byte_contents
¶ Return the contents as raw byte array.
-
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.
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.
-
path
¶ Return the full path of the current object.
-
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
-
contents
¶ Return the list of contained directory entries.
-
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.
-
size
¶ Return the total size of all files contained in this directory tree.
Unittest module classes¶
-
class
pyfakefs.fake_filesystem_unittest.
TestCase
(methodName='runTest', additional_skip_names=None, patch_path=True, modules_to_reload=None, use_dynamic_patch=True, modules_to_patch=None)¶ Test case class that automatically replaces file-system related modules by fake implementations.
Creates the test class instance and the stubber used to stub out file system related modules.
Parameters: methodName – The name of the test method (same as in unittest.TestCase) -
setUpPyfakefs
()¶ 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.
-
-
class
pyfakefs.fake_filesystem_unittest.
Patcher
(additional_skip_names=None, patch_path=True, modules_to_reload=None, use_dynamic_patch=True, modules_to_patch=None)¶ Instantiate a stub creator to bind and un-bind the file-related modules to the
pyfakefs
fake modules.The arguments are explained in
TestCase
.Patcher
is used inTestCase
.Patcher
also works as a context manager for PyTest: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().
-
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.
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 standardos
module since Python 3.5. This class handles the separatescandir
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)