README.md
1# pyfakefs [](https://badge.fury.io/py/pyfakefs) [](https://img.shields.io/pypi/pyversions/pyfakefs.svg)
2
3pyfakefs implements a fake file system that mocks the Python file system modules.
4Using pyfakefs, your tests operate on a fake file system in memory without
5touching the real disk. The software under test requires no modification to
6work with pyfakefs.
7
8pyfakefs works with Linux, Windows and MacOS.
9
10## Documentation
11
12This file provides general usage instructions for pyfakefs. There is more:
13
14* The documentation at [GitHub Pages:](http://jmcgeheeiv.github.io/pyfakefs)
15 * The [Release documentation](http://jmcgeheeiv.github.io/pyfakefs/release)
16 contains usage documentation for pyfakefs and a description of the
17 most relevent classes, methods and functions for the last version
18 released on PyPi
19 * The [Development documentation](http://jmcgeheeiv.github.io/pyfakefs/master)
20 contains the same documentation for the current master branch
21 * The [Release 3.7 documentation](http://jmcgeheeiv.github.io/pyfakefs/release37)
22 contains usage documentation for the last version of pyfakefs
23 supporting Python 2.7
24 * The [Release 3.3 documentation](http://jmcgeheeiv.github.io/pyfakefs/release33)
25 contains usage documentation for the last version of pyfakefs
26 supporting Python 2.6, and for the old-style API (which is still
27 supported but not documented in the current release)
28* The [Release Notes](https://github.com/jmcgeheeiv/pyfakefs/blob/master/CHANGES.md)
29 show a list of changes in the latest versions
30
31### Linking to pyfakefs
32
33In your own documentation, please link to pyfakefs using the canonical URL <http://pyfakefs.org>.
34This URL always points to the most relevant top page for pyfakefs.
35
36## Usage
37
38pyfakefs has support for `unittest` and `pytest`, but can also be used
39directly using `fake_filesystem_unittest.Patcher`. Refer to the
40[usage documentation](http://jmcgeheeiv.github.io/pyfakefs/master/usage.html)
41for more information on test scenarios, test customization and
42using convenience functions.
43
44
45## Compatibility
46pyfakefs works with CPython 3.5 and above, on Linux, Windows and OSX
47(MacOS), and with PyPy3.
48
49pyfakefs works with [PyTest](http://doc.pytest.org) version 2.8.6 or above.
50
51pyfakefs will not work with Python libraries that use C libraries to access the
52file system. This is because pyfakefs cannot patch the underlying C libraries'
53file access functions--the C libraries will always access the real file system.
54For example, pyfakefs will not work with [`lxml`](http://lxml.de/). In this case
55`lxml` must be replaced with a pure Python alternative such as
56[`xml.etree.ElementTree`](https://docs.python.org/3/library/xml.etree.elementtree.html).
57
58## Development
59
60### Continuous integration
61
62pyfakefs is currently automatically tested:
63* [](https://travis-ci.org/jmcgeheeiv/pyfakefs)
64 on Linux, with Python 3.5 to 3.8, using [Travis](https://travis-ci.org/jmcgeheeiv/pyfakefs)
65* [](https://travis-ci.org/jmcgeheeiv/pyfakefs)
66 on MacOS, with Python 3.6 to 3.8, using [Travis](https://travis-ci.org/jmcgeheeiv/pyfakefs)
67* [](https://ci.appveyor.com/project/jmcgeheeiv/pyfakefs/branch/master)
68 on Windows, with Python 3.5 to 3.8 using [Appveyor](https://ci.appveyor.com/project/jmcgeheeiv/pyfakefs)
69
70### Running pyfakefs unit tests
71
72#### On the command line
73pyfakefs unit tests can be run using `unittest` or `pytest`:
74
75```bash
76$ cd pyfakefs/
77$ export PYTHONPATH=$PWD
78
79$ python -m pyfakefs.tests.all_tests
80$ python -m pyfakefs.tests.all_tests_without_extra_packages
81$ python -m pytest pyfakefs/pytest_tests/pytest_plugin_test.py
82```
83
84These scripts are called by `tox` and Travis-CI. `tox` can be used to run tests
85locally against supported python versions:
86
87```bash
88$ tox
89```
90
91#### In a Docker container
92
93The `Dockerfile` at the top of the repository will run the tests on the latest
94Ubuntu version. Build the container:
95```bash
96cd pyfakefs/
97docker build -t pyfakefs .
98```
99Run the unit tests in the container:
100```bash
101docker run -t pyfakefs
102```
103
104### Contributing to pyfakefs
105
106We always welcome contributions to the library. Check out the [Contributing
107Guide](https://github.com/jmcgeheeiv/pyfakefs/blob/master/CONTRIBUTING.md)
108for more information.
109
110## History
111pyfakefs.py was initially developed at Google by Mike Bland as a modest fake
112implementation of core Python modules. It was introduced to all of Google
113in September 2006. Since then, it has been enhanced to extend its
114functionality and usefulness. At last count, pyfakefs is used in over 2,000
115Python tests at Google.
116
117Google released pyfakefs to the public in 2011 as Google Code project
118[pyfakefs](http://code.google.com/p/pyfakefs/):
119* Fork
120 [jmcgeheeiv-pyfakefs](http://code.google.com/p/jmcgeheeiv-pyfakefs/) added
121 [direct support for unittest and doctest](../../wiki/Automatically-find-and-patch-file-functions-and-modules)
122* Fork
123 [shiffdane-jmcgeheeiv-pyfakefs](http://code.google.com/p/shiffdane-jmcgeheeiv-pyfakefs/)
124 added further corrections
125
126After the [shutdown of Google Code](http://google-opensource.blogspot.com/2015/03/farewell-to-google-code.html)
127was announced, [John McGehee](https://github.com/jmcgeheeiv) merged all three Google Code projects together
128[here on GitHub](https://github.com/jmcgeheeiv/pyfakefs) where an enthusiastic community actively supports, maintains
129and extends pyfakefs.
130
){kind=link}
){kind=link}
){kind=link}