1Introduction 2============ 3 4`pyfakefs <https://github.com/pytest-dev/pyfakefs>`__ implements a fake file 5system that mocks the Python file system modules. 6Using pyfakefs, your tests operate on a fake file system in memory without touching the real disk. 7The software under test requires no modification to work with pyfakefs. 8 9pyfakefs works with CPython 3.8 and above, on Linux, Windows and macOS, 10and with PyPy3. 11 12pyfakefs works with `pytest <doc.pytest.org>`__ version 3.0.0 or above by 13providing the `fs` fixture that enables the fake filesystem. 14 15Installation 16------------ 17pyfakefs is available on `PyPI <https://pypi.python.org/pypi/pyfakefs/>`__. 18The latest released version can be installed from PyPI: 19 20.. code:: bash 21 22 pip install pyfakefs 23 24The latest main can be installed from the GitHub sources: 25 26.. code:: bash 27 28 pip install git+https://github.com/pytest-dev/pyfakefs 29 30Features 31-------- 32- Code executed under pyfakefs works transparently on a memory-based file 33 system without the need of special commands. The same code that works on 34 the real filesystem will work on the fake filesystem if running under 35 pyfakefs. 36 37- pyfakefs provides direct support for `pytest` (via the `fs` fixture) 38 and `unittest` (via a `TestCase` base class), but can also be used with 39 other test frameworks. 40 41- Each pyfakefs test starts with an empty file system, but it is possible to 42 map files and directories from the real file system into the fake 43 filesystem if needed. 44 45- No files in the real file system are changed during the tests, even in the 46 case of writing to mapped real files. 47 48- pyfakefs keeps track of the filesystem size if configured. The file system 49 size can be configured arbitrarily. 50 51- it is possible to pause and resume using the fake filesystem, if the 52 real file system has to be used in a test step 53 54- pyfakefs defaults to the OS it is running on, but can also be configured 55 to test code running under another OS (Linux, macOS or Windows). 56 57- pyfakefs can be configured to behave as if running as a root or as a 58 non-root user, independently from the actual user. 59 60.. _limitations: 61 62Limitations 63----------- 64- pyfakefs will not work with Python libraries (other than `os` and `io`) that 65 use C libraries to access the file system, because it cannot patch the 66 underlying C libraries' file access functions 67 68- pyfakefs patches most kinds of importing file system modules automatically, 69 but there are still some cases where this will not work. 70 See :ref:`customizing_patcher` for more information and ways to work around 71 this. 72 73- pyfakefs does not retain the MRO for file objects, so you cannot rely on 74 checks using `isinstance` for these objects (for example, to differentiate 75 between binary and textual file objects). 76 77- pyfakefs is only tested with CPython and the newest PyPy versions, other 78 Python implementations will probably not work 79 80- Differences in the behavior in different Linux distributions or different 81 macOS or Windows versions may not be reflected in the implementation, as 82 well as some OS-specific low-level file system behavior. The systems used 83 for automatic tests in GitHub Actions are 84 considered as reference systems. Additionally, the tests are run in Docker 85 containers with the latest CentOS, Debian, Fedora and Ubuntu images. 86 87- pyfakefs may not work correctly if file system functions are patched by 88 other means (e.g. using `unittest.mock.patch`) - see 89 :ref:`usage_with_mock_open` for more information 90 91- pyfakefs will not work correctly with 92 `behave <https://github.com/behave/behave>`__ due to the way it loads 93 the steps, if any filesystem modules are imported globally in the steps or 94 environment files; as a workaround, you may load them locally inside the 95 test steps (see `this issue <https://github.com/pytest-dev/pyfakefs/issues/703>`__) 96 97History 98------- 99pyfakefs was initially developed at Google by 100`Mike Bland <https://mike-bland.com/about.html>`__ as a modest 101fake implementation of core Python modules. It was introduced to all of 102Google in September 2006. Since then, it has been enhanced to extend its 103functionality and usefulness. At last count, pyfakefs was used in over 1042,000 Python tests at Google. 105 106Google released pyfakefs to the public in 2011 as Google Code project 107`pyfakefs <http://code.google.com/p/pyfakefs/>`__: 108 109* Fork `jmcgeheeiv-pyfakefs <http://code.google.com/p/jmcgeheeiv-pyfakefs/>`__ 110 added direct support for unittest and doctest as described in 111 :ref:`auto_patch` 112* Fork `shiffdane-jmcgeheeiv-pyfakefs <http://code.google.com/p/shiffdane-jmcgeheeiv-pyfakefs/>`__ 113 added further corrections 114 115After the `shutdown of Google 116Code <http://google-opensource.blogspot.com/2015/03/farewell-to-google-code.html>`__ 117was announced, `John McGehee <https://github.com/jmcgeheeiv>`__ merged 118all three Google Code projects together `on 119GitHub <https://github.com/pytest-dev/pyfakefs>`__ where an enthusiastic 120community actively maintains and extends pyfakefs. In 2022, the repository has 121been transferred to `pytest-dev <https://github.com/pytest-dev>`__ to ensure 122continuous maintenance. 123