Fix documentation for cleanup handlers

- add convenience handler 'reload_cleanup_handler'

CHANGES.md

@@ -18,6 +18,8 @@ The released versions correspond to PyPI releases.
 * fixed a problem with module and session scoped fixtures in Python 3.13
   (see [#1101](../../issues/1101))
 * fixed handling of `cwd` if set to a `pathlib.Path` (see [#1108](../../issues/1108))
+* fixed documentation for cleanup handlers, added convenience handler `reload_cleanup_handler`
+  (see [#1105](../../issues/1105))
 
 ## [Version 5.7.3](https://pypi.python.org/pypi/pyfakefs/5.7.3) (2024-12-15)
 Fixes a regression in version 5.7.3.

docs/troubleshooting.rst

@@ -374,9 +374,25 @@ be added to the patcher:
 
   @pytest.fixture
   def my_fs():
-      with Patcher():
-          patcher["modulename"] = handler_no_cleanup
-          yield
+      with Patcher() as patcher:
+          patcher.cleanup_handlers["modulename"] = handler_no_cleanup
+          yield patcher.fs
+
+
+A specific problem are modules that use filesystem functions and are imported by other modules locally
+(e.g. inside a function). These kinds of modules are not correctly reset and need to be reloaded manually.
+For this case, the cleanup handler `reload_cleanup_handler` in `pyfakefs.helpers` can be used:
+
+.. code:: python
+
+  from pyfakefs.helpers import reload_cleanup_handler
+
+
+  @pytest.fixture
+  def my_fs():
+      with Patcher() as patcher:
+          patcher.cleanup_handlers["modulename"] = reload_cleanup_handler
+          yield patcher.fs
 
 As this may not be trivial, we recommend to write an issue in ``pyfakefs`` with a reproducible example.
 We will analyze the problem, and if we find a solution we will either get this fixed in ``pyfakefs``

pyfakefs/helpers.py

@@ -13,6 +13,7 @@
 """Helper classes use for fake file system implementation."""
 
 import ctypes
+import importlib
 import io
 import locale
 import os
@@ -539,3 +540,12 @@ def starts_with(path, string):
         ):
             return True
     return False
+
+
+def reload_cleanup_handler(name):
+    """Cleanup handler that reloads the module with the given name.
+    Maybe needed in cases where a module is imported locally.
+    """
+    if name in sys.modules:
+        importlib.reload(sys.modules[name])
+    return True

pyfakefs/pytest_tests/lib_using_pathlib.py

@@ -0,0 +1,5 @@
+import pathlib
+
+
+def use_pathlib(path: str):
+    return pathlib.Path(path)

pyfakefs/pytest_tests/local_import.py

@@ -0,0 +1,4 @@
+def load(path: str) -> str:
+    from pyfakefs.pytest_tests import lib_using_pathlib
+
+    return lib_using_pathlib.use_pathlib(path)

pyfakefs/pytest_tests/test_reload_local_import.py

@@ -0,0 +1,26 @@
+import pytest
+
+from pyfakefs.fake_filesystem_unittest import Patcher
+from pyfakefs.fake_pathlib import FakePathlibModule
+from pyfakefs.helpers import reload_cleanup_handler
+from pyfakefs.pytest_tests import local_import
+
+
+@pytest.fixture
+def test_fs():
+    with Patcher() as patcher:
+        patcher.cleanup_handlers["pyfakefs.pytest_tests.lib_using_pathlib"] = (
+            reload_cleanup_handler
+        )
+        yield patcher.fs
+
+
+class TestReloadCleanupHandler:
+    def test1(self, test_fs):
+        path = local_import.load("some_path")
+        assert isinstance(path, FakePathlibModule.Path)
+
+    def test2(self):
+        path = local_import.load("some_path")
+        # will fail without reload handler
+        assert not isinstance(path, FakePathlibModule.Path)