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