From 99a8a2dafb15a1f07f37dd829485c776f4e4bd5c Mon Sep 17 00:00:00 2001 From: mrbean-bremen Date: Wed, 6 Mar 2024 09:09:54 +0100 Subject: Add chapter about nested fake filesystems to troubleshouting guide --- CHANGES.md | 38 +++++++++++++++++++------------------- docs/troubleshooting.rst | 48 +++++++++++++++++++++++++++++++++++++++++++++++- docs/usage.rst | 2 +- 3 files changed, 67 insertions(+), 21 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index bfbad4a..640a73a 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -4,38 +4,38 @@ The released versions correspond to PyPI releases. ## Unreleased ### Changes -* The handling of file permissions under Posix is should now mostly match the behavior +* the handling of file permissions under Posix is should now mostly match the behavior of the real filesystem, which may change the behavior of some tests ### Fixes -* Fixed a specific problem on reloading a pandas-related module (see [#947](../../issues/947)), +* fixed a specific problem on reloading a pandas-related module (see [#947](../../issues/947)), added possibility for unload hooks for specific modules -* Use this also to reload django views (see [#932](../../issues/932)) -* Fixed `EncodingWarning` for Python >= 3.11 (see [#957](../../issues/957)) -* Consider directory ownership while adding or removing directory entries +* use this also to reload django views (see [#932](../../issues/932)) +* fixed `EncodingWarning` for Python >= 3.11 (see [#957](../../issues/957)) +* consider directory ownership while adding or removing directory entries (see [#959](../../issues/959)) -* Fixed handling of directory enumeration and search permissions under Posix systems +* fixed handling of directory enumeration and search permissions under Posix systems (see [#960](../../issues/960)) ## [Version 5.3.5](https://pypi.python.org/pypi/pyfakefs/5.3.5) (2024-01-30) Fixes a regression. ### Fixes -* Fixes a regression due to the changed behavior of the dynamic patcher cleanup (see [#939](../../issues/939)). +* Fixed a regression due to the changed behavior of the dynamic patcher cleanup (see [#939](../../issues/939)). The change is now by default only made if the `django` module is loaded, and the behavior can be changed using the new argument `module_cleanup_mode`. ### Packaging -* include `tox.ini` and a few more files into the source distribution (see [#937](../../issues/937)) +* included `tox.ini` and a few more files into the source distribution (see [#937](../../issues/937)) ## [Version 5.3.4](https://pypi.python.org/pypi/pyfakefs/5.3.4) (2024-01-19) Bugfix release. ### Fixes -* fixes handling of unhashable modules which cannot be cached (see [#923](../../issues/923)) +* fixed handling of unhashable modules which cannot be cached (see [#923](../../issues/923)) * reload modules loaded by the dynamic patcher instead of removing them - sometimes they may not be reloaded automatically (see [#932](../../issues/932)) -* add back argument `use_dynamic_patch` as a fallback for similar problems +* added back argument `use_dynamic_patch` as a fallback for similar problems ## [Version 5.3.2](https://pypi.python.org/pypi/pyfakefs/5.3.2) (2023-11-30) @@ -58,23 +58,23 @@ Mostly a bugfix release. to an existing directory in the fake filesystem (see [#901](../../issues/901)) ### Fixes -* fixes the problem that filesystem patching was still active in the pytest +* fixed the problem that filesystem patching was still active in the pytest logreport phase (see [#904](../../issues/904)) -* Restores compatibility with PyTorch 2.0 and above, as well as with other - classes that have custom __setattr__ methods (see [#905](../../pull/905)). +* restored compatibility with PyTorch 2.0 and above, as well as with other + classes that have custom __setattr__ methods (see [#905](../../pull/905)) ## [Version 5.3.0](https://pypi.python.org/pypi/pyfakefs/5.3.0) (2023-10-11) Adds official support for Python 3.12. ### Changes -* add official support for Python 3.12 +* added official support for Python 3.12 ### Fixes * removed a leftover debug print statement (see [#869](../../issues/869)) * make sure tests work without HOME environment set (see [#870](../../issues/870)) * automount drive or UNC path under Windows if needed for `pathlib.Path.mkdir()` (see [#890](../../issues/890)) -* adapt patching `io.open` and `io.open_code` to work with Python 3.12 +* adapted patching `io.open` and `io.open_code` to work with Python 3.12 (see [#836](../../issues/836) and [#892](../../issues/892)) ## [Version 5.2.4](https://pypi.python.org/pypi/pyfakefs/5.2.4) (2023-08-18) @@ -91,12 +91,12 @@ Adds compatibility with PyPy 3.10 and Python 3.12. ### Fixes * Re-create temp directory if it had been created before on resetting file system (see [#814](../../issues/814)). -* Exclude pytest `pathlib` modules from patching to avoid mixup of patched/unpatched +* Excluded pytest `pathlib` modules from patching to avoid mixup of patched/unpatched code (see [#814](../../issues/814)). -* Adapt to changes in Python 3.12 beta1 (only working partially, +* Adapted to changes in Python 3.12 beta1 (only working partially, see [#830](../../issues/830) and [#831](../../issues/831)). -* Adapt to changes in `shutil` in Python 3.12 beta2 (see [#814](../../issues/814)). -* Fix support for newer PyPi versions (see [#859](../../issues/859)). +* Adapted to changes in `shutil` in Python 3.12 beta2 (see [#814](../../issues/814)). +* Fixed support for newer PyPi versions (see [#859](../../issues/859)). ### Documentation * Added a note regarding the incompatibility of the built-in `sqlite3` module with diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst index d02551b..56572aa 100644 --- a/docs/troubleshooting.rst +++ b/docs/troubleshooting.rst @@ -134,6 +134,8 @@ from configuration files. In these cases, you have to map the respective files or directories from the real into the fake filesystem as described in :ref:`real_fs_access`. For the timezone example, this could look like the following:: +.. code:: python + from pathlib import Path import pytz from pyfakefs.fake_filesystem_unittest import TestCase @@ -150,13 +152,15 @@ or directories from the real into the fake filesystem as described in If you are using Django, various dependencies may expect both the project directory and the ``site-packages`` installation to exist in the fake filesystem. -Here's an example of how to add these using pytest:: +Here's an example of how to add these using pytest: +.. code:: python import os import django import pytest + @pytest.fixture def fake_fs(fs): PROJECT_BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) @@ -279,6 +283,48 @@ is problematic and better avoided. `pathlib` has been restructured so that a pathlib path no longer contains a reference to the original filesystem accessor, and it can safely be used in the fake filesystem. +.. _nested_patcher_invocation: + +Nested file system fixtures and Patcher invocations +--------------------------------------------------- +``pyfakefs`` does not support nested faked file systems. Instead, it uses reference counting +on the single fake filesystem instance. That means, if you are trying to create a fake filesystem +inside a fake filesystem, only the reference count will increase, and any arguments you may pass +to the patcher or fixture are ignored. Likewise, if you leave a nested fake filesystem, +only the reference count is decreased and nothing is reverted. + +There are some situations where that may happen, probably without you noticing: + +* If you use the module- or session based variants of the ``fs`` fixture (e.g. ``fs_module`` or + ``fs_session``), you may still use the ``fs`` fixture in single tests. This will practically + reference the module- or session based fake filesystem, instead of creating a new one. + +.. code:: python + + @pytest.fixture(scope="module", autouse=True) + def use_fs(fs_module): + # do some setup... + yield fs_module + + + def test_something(fs): + do_more_fs_setup() + test_something() + # the fs setup done in this test is not reverted! + +* If you invoke a ``Patcher`` instance inside a test with the ``fs`` fixture (or with an active + ``fs_module`` or ``fs_session`` fixture), this will be ignored. For example: + +.. code:: python + + def test_something(fs): + with Patcher(allow_root_user=False): + # root user is still allowed + do_stuff() + +* The same is true, if you use ``setUpPyfakefs`` or ``setUpClassPyfakefs`` in a unittest context, or if you use + the ``patchfs`` decorator. ``Patcher`` instances created in the tests will be ignored likewise. + .. _`multiprocessing`: https://docs.python.org/3/library/multiprocessing.html .. _`subprocess`: https://docs.python.org/3/library/subprocess.html diff --git a/docs/usage.rst b/docs/usage.rst index 5332541..9cfe0ed 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -51,7 +51,7 @@ respectively. not setup / tear down the fake filesystem in the current scope; instead, it will just serve as a reference to the active fake filesystem. That means that changes done in the fake filesystem inside a test will remain there until the respective scope - ends. + ends (see also :ref:`nested_patcher_invocation`). Patch using fake_filesystem_unittest ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.2.3