diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 112 |
1 files changed, 63 insertions, 49 deletions
@@ -1,84 +1,97 @@ -# pyfakefs [](https://badge.fury.io/py/pyfakefs) [](https://img.shields.io/pypi/pyversions/pyfakefs.svg)  +# pyfakefs [](https://badge.fury.io/py/pyfakefs) [](https://img.shields.io/pypi/pyversions/pyfakefs.svg)  [](https://pytest-pyfakefs.readthedocs.io/en/latest/?badge=latest) [](https://results.pre-commit.ci/latest/github/pytest-dev/pyfakefs/main) + pyfakefs implements a fake file system that mocks the Python file system modules. Using pyfakefs, your tests operate on a fake file system in memory without -touching the real disk. The software under test requires no modification to +touching the real disk. The software under test requires no modification to work with pyfakefs. -pyfakefs works with Linux, Windows and MacOS. +Pyfakefs creates a new empty in-memory file system at each test start, which replaces +the real filesystem during the test. Think of pyfakefs as making a per-test temporary +directory, except for an entire file system. + +There are several means to achieve this: by using +the `fs` fixture if running pytest, by using `fake_filesystem_unittest.TestCase` as a +base class if using unittest, by using a `fake_filesystem_unittest.Patcher` instance +as a context manager, or by using the `patchfs` decorator. + + + +pyfakefs works with current versions of Linux, Windows and macOS. ## Documentation -This file provides general usage instructions for pyfakefs. There is more: - -* The documentation at [GitHub Pages:](http://jmcgeheeiv.github.io/pyfakefs) - * The [Release documentation](http://jmcgeheeiv.github.io/pyfakefs/release) - contains usage documentation for pyfakefs and a description of the - most relevant classes, methods and functions for the last version - released on PyPi - * The [Development documentation](http://jmcgeheeiv.github.io/pyfakefs/master) - contains the same documentation for the current master branch - * The [Release 3.7 documentation](http://jmcgeheeiv.github.io/pyfakefs/release37) - contains usage documentation for the last version of pyfakefs +This document provides a general overview for pyfakefs. There is more: + +* The documentation at **Read the Docs**: + * The [Release documentation](https://pytest-pyfakefs.readthedocs.io/en/stable) + contains usage documentation for pyfakefs and a description of the + most relevant classes, methods and functions for the last version + released on PyPI + * The [Development documentation](https://pytest-pyfakefs.readthedocs.io/en/latest) + contains the same documentation for the current main branch + * The [Release 3.7 documentation](https://pytest-pyfakefs.readthedocs.io/en/v3.7.2/) + contains usage documentation for the last version of pyfakefs supporting Python 2.7 - * The [Release 3.3 documentation](http://jmcgeheeiv.github.io/pyfakefs/release33) - contains usage documentation for the last version of pyfakefs - supporting Python 2.6, and for the old-style API (which is still - supported but not documented in the current release) -* The [Release Notes](https://github.com/jmcgeheeiv/pyfakefs/blob/master/CHANGES.md) +* The [Release Notes](https://github.com/pytest-dev/pyfakefs/blob/main/CHANGES.md) show a list of changes in the latest versions -### Linking to pyfakefs - -In your own documentation, please link to pyfakefs using the canonical URL <http://pyfakefs.org>. -This URL always points to the most relevant top page for pyfakefs. - ## Usage - -pyfakefs has support for `unittest` and `pytest`, but can also be used -directly using `fake_filesystem_unittest.Patcher`. Refer to the -[usage documentation](http://jmcgeheeiv.github.io/pyfakefs/master/usage.html) -for more information on test scenarios, test customization and +The simplest method to use pyfakefs is using the `fs` fixture with `pytest`. +Refer to the +[usage documentation](https://pytest-pyfakefs.readthedocs.io/en/latest/usage.html) +for information on other test scenarios, test customization and using convenience functions. +## Features +Apart from automatically mocking most file-system functions, pyfakefs +provides some additional features: +- mapping files and directories from the real file system into the fake filesystem +- configuration and tracking of the file system size +- pause and resume of patching to be able to use the real file system inside a + test step +- (limited) emulation of other OSes (Linux, macOS or Windows) +- configuration to behave as if running as a non-root user while running + under root ## Compatibility -pyfakefs works with CPython 3.6 and above, on Linux, Windows and OSX -(MacOS), and with PyPy3. +pyfakefs works with CPython 3.8 and above, on Linux, Windows and macOS, and +with PyPy3. -pyfakefs works with [pytest](http://doc.pytest.org) version 3.0.0 or above. +pyfakefs works with [pytest](http://doc.pytest.org) version 3.0.0 or above, +though a current version is recommended. pyfakefs will not work with Python libraries that use C libraries to access the -file system. This is because pyfakefs cannot patch the underlying C libraries' -file access functions--the C libraries will always access the real file system. -For example, pyfakefs will not work with [`lxml`](http://lxml.de/). In this case -`lxml` must be replaced with a pure Python alternative such as -[`xml.etree.ElementTree`](https://docs.python.org/3/library/xml.etree.elementtree.html). +file system. This is because pyfakefs cannot patch the underlying C libraries' +file access functions--the C libraries will always access the real file +system. Refer to the +[documentation](https://pytest-pyfakefs.readthedocs.io/en/latest/intro.html#limitations) +for more information about the limitations of pyfakefs. ## Development ### Continuous integration -pyfakefs is currently automatically tested on Linux, MacOS and Windows, with -Python 3.6 to 3.10, and with PyPy3 on Linux, using -[GitHub Actions](https://github.com/jmcgeheeiv/pyfakefs/actions). +pyfakefs is currently automatically tested on Linux, macOS and Windows, with +Python 3.8 to 3.12, and with PyPy3 on Linux, using +[GitHub Actions](https://github.com/pytest-dev/pyfakefs/actions). ### Running pyfakefs unit tests #### On the command line -pyfakefs unit tests can be run using `unittest` or `pytest`: +pyfakefs unit tests can be run using `pytest` (all tests) or `unittest` +(all tests except `pytest`-specific ones): ```bash $ cd pyfakefs/ $ export PYTHONPATH=$PWD +$ python -m pytest pyfakefs $ python -m pyfakefs.tests.all_tests -$ python -m pyfakefs.tests.all_tests_without_extra_packages -$ python -m pytest pyfakefs/pytest_tests/pytest_plugin_test.py ``` -These scripts are called by `tox` and Travis-CI. `tox` can be used to run tests -locally against supported python versions: +Similar scripts are called by `tox` and Github Actions. `tox` can be used to +run tests locally against supported python versions: ```bash $ tox @@ -100,14 +113,14 @@ docker run -t pyfakefs ### Contributing to pyfakefs We always welcome contributions to the library. Check out the -[Contributing Guide](https://github.com/jmcgeheeiv/pyfakefs/blob/master/CONTRIBUTING.md) +[Contributing Guide](https://github.com/pytest-dev/pyfakefs/blob/main/CONTRIBUTING.md) for more information. ## History pyfakefs.py was initially developed at Google by Mike Bland as a modest fake implementation of core Python modules. It was introduced to all of Google in September 2006. Since then, it has been enhanced to extend its -functionality and usefulness. At last count, pyfakefs is used in over 2,000 +functionality and usefulness. At last count, pyfakefs was used in over 2,000 Python tests at Google. Google released pyfakefs to the public in 2011 as Google Code project @@ -121,5 +134,6 @@ Google released pyfakefs to the public in 2011 as Google Code project After the [shutdown of Google Code](http://google-opensource.blogspot.com/2015/03/farewell-to-google-code.html) was announced, [John McGehee](https://github.com/jmcgeheeiv) merged all three Google Code projects together -[here on GitHub](https://github.com/jmcgeheeiv/pyfakefs) where an enthusiastic community actively supports, maintains -and extends pyfakefs. +[here on GitHub](https://github.com/pytest-dev/pyfakefs) where an enthusiastic community actively supports, maintains +and extends pyfakefs. In 2022, the repository has been transferred to +[pytest-dev](https://github.com/pytest-dev) to ensure continuous maintenance. |