Add thread lock for global patches

- remove incorrect documentation about stand-alone usage
- fix patching of global variables

Author: mrbean-bremen

CHANGES.md

@@ -17,7 +17,7 @@ The released versions correspond to PyPI releases.
 ### Changes
 * the message from an `OSError` raised in the fake filesystem has no longer the postfix
   _"in the fake filesystem"_ (see [#1159](../../discussions/1159))
-* changed implementation of `FakeShutilModule` to be able to be used without the patcher
+* changed implementation of `FakeShutilModule` to prepare it for usage without the patcher
   (see [#1171](../../discussions/1171))
 
 ### Enhancements

pyfakefs/fake_filesystem_shutil.py

@@ -23,28 +23,17 @@
 
 :Usage:
 
-* With Patcher:
-  The fake implementation is automatically involved if using
-  `fake_filesystem_unittest.TestCase`, pytest fs fixture,
-  or directly `Patcher`.
-
-* Stand-alone with FakeFilesystem:
-  To patch it independently of these, you also need to patch `os`, e.g:
-
-    filesystem = fake_filesystem.FakeFilesystem()
-    fake_os = fake_os.FakeOsModule(filesystem)
-    fake_shutil = fake_filesystem_shutil.FakeShutilModule(filesystem)
-
-    with patch("os", fake_os):
-        with patch("shutil.os", shutil_mock):
-            shutil.rmtree("path/in/fakefs")
-
+The fake implementation is automatically involved if using
+`fake_filesystem_unittest.TestCase`, pytest fs fixture,
+or directly `Patcher`.
 """
 
-import contextlib
+import functools
 import os
 import shutil
 import sys
+from threading import Lock
+from typing import Callable
 
 
 class FakeShutilModule:
@@ -53,24 +42,19 @@ class FakeShutilModule:
 
     Automatically created if using `fake_filesystem_unittest.TestCase`,
     the `fs` fixture, the `patchfs` decorator, or directly the `Patcher`.
-
-    To patch it separately, you also need to patch `os`::
-
-        filesystem = fake_filesystem.FakeFilesystem()
-        fake_os = fake_os.FakeOsModule(filesystem)
-        fake_shutil = fake_filesystem_shutil.FakeShutilModule(filesystem)
-
-        with patch("os", fake_os):
-            with patch("shutil.os", shutil_mock):
-                shutil.rmtree("path/in/fakefs")
     """
 
+    module_lock = Lock()
+
     use_copy_file_range = (
         hasattr(shutil, "_USE_CP_COPY_FILE_RANGE") and shutil._USE_CP_COPY_FILE_RANGE  # type: ignore[attr-defined]
     )
     has_fcopy_file = hasattr(shutil, "_HAS_FCOPYFILE") and shutil._HAS_FCOPYFILE  # type: ignore[attr-defined]
     use_sendfile = hasattr(shutil, "_USE_CP_SENDFILE") and shutil._USE_CP_SENDFILE  # type: ignore[attr-defined]
     use_fd_functions = shutil._use_fd_functions  # type: ignore[attr-defined]
+    functions_to_patch = ["copy", "copyfile", "rmtree"]
+    if sys.version_info < (3, 12) or sys.platform != "win32":
+        functions_to_patch.extend(["copy2", "copytree", "move"])
 
     @staticmethod
     def dir():
@@ -89,12 +73,12 @@ def __init__(self, filesystem):
         self.shutil_module = shutil
         self._in_get_attribute = False
 
-    def start_patching_global_vars(self):
-        if self.__class__.has_fcopy_file:
+    def _start_patching_global_vars(self):
+        if self.has_fcopy_file:
             self.shutil_module._HAS_FCOPYFILE = False
-        if self.__class__.use_copy_file_range:
+        if self.use_copy_file_range:
             self.shutil_module._USE_CP_COPY_FILE_RANGE = False
-        if self.__class__.use_sendfile:
+        if self.use_sendfile:
             self.shutil_module._USE_CP_SENDFILE = False
         if self.use_fd_functions:
             if sys.version_info >= (3, 14):
@@ -104,28 +88,36 @@ def start_patching_global_vars(self):
             else:
                 self.shutil_module._use_fd_functions = False
 
-    def stop_patching_global_vars(self):
-        if self.__class__.has_fcopy_file:
+    def _stop_patching_global_vars(self):
+        if self.has_fcopy_file:
             self.shutil_module._HAS_FCOPYFILE = True
-        if self.__class__.use_copy_file_range:
+        if self.use_copy_file_range:
             self.shutil_module._USE_CP_COPY_FILE_RANGE = True
-        if self.__class__.use_sendfile:
+        if self.use_sendfile:
             self.shutil_module._USE_CP_SENDFILE = True
-        if self.__class__.use_fd_functions:
+        if self.use_fd_functions:
             if sys.version_info >= (3, 14):
-                self.__class__.shutil_module._rmtree_impl = (
+                self.shutil_module._rmtree_impl = (
                     self.shutil_module._rmtree_safe_fd  # type: ignore[attr-defined]
                 )
             else:
                 self.shutil_module._use_fd_functions = True
 
-    @contextlib.contextmanager
-    def patch_global_vars(self):
-        self.start_patching_global_vars()
-        try:
-            yield
-        finally:
-            self.start_patching_global_vars()
+    def with_patched_globals(self, f: Callable) -> Callable:
+        """Function wrapper that patches global variables during function execution.
+        Can be used in multi-threading code.
+        """
+
+        @functools.wraps(f)
+        def wrapped(*args, **kwargs):
+            with self.module_lock:
+                self._start_patching_global_vars()
+                try:
+                    return f(*args, **kwargs)
+                finally:
+                    self._stop_patching_global_vars()
+
+        return wrapped
 
     def disk_usage(self, path):
         """Return the total, used and free disk space in bytes as named tuple
@@ -136,32 +128,6 @@ def disk_usage(self, path):
         """
         return self.filesystem.get_disk_usage(path)
 
-    if sys.version_info < (3, 11):
-
-        def rmtree(self, path, ignore_errors=False, onerror=None):
-            with self.patch_global_vars():
-                self.shutil_module.rmtree(path, ignore_errors, onerror)
-
-    elif sys.version_info < (3, 12):
-
-        def rmtree(self, path, ignore_errors=False, onerror=None, *, dir_fd=None):
-            with self.patch_global_vars():
-                self.shutil_module.rmtree(path, ignore_errors, onerror, dir_fd=dir_fd)
-
-    else:
-
-        def rmtree(
-            self, path, ignore_errors=False, onerror=None, *, onexc=None, dir_fd=None
-        ):
-            with self.patch_global_vars():
-                self.shutil_module.rmtree(
-                    path, ignore_errors, onerror, onexc=onexc, dir_fd=dir_fd
-                )
-
-    def copyfile(self, src, dst, *, follow_symlinks=True):
-        with self.patch_global_vars():
-            self.shutil_module.copyfile(src, dst, follow_symlinks=follow_symlinks)
-
     if sys.version_info >= (3, 12) and sys.platform == "win32":
 
         def copy2(self, src, dst, *, follow_symlinks=True):
@@ -207,4 +173,6 @@ def move(self, src, dst, copy_function=shutil.copy2):
 
     def __getattr__(self, name):
         """Forwards any non-faked calls to the standard shutil module."""
+        if name in self.functions_to_patch:
+            return self.with_patched_globals(getattr(self.shutil_module, name))
         return getattr(self.shutil_module, name)

pyfakefs/fake_pathlib.py

@@ -15,15 +15,9 @@
 
 Usage:
 
-* With Patcher:
-  If using `fake_filesystem_unittest.TestCase`, pytest fs fixture,
-  or directly `Patcher`, pathlib gets replaced
-  by fake_pathlib together with other file system related modules.
-
-* Stand-alone with FakeFilesystem:
-  `filesystem = fake_filesystem.FakeFilesystem()`
-  `fake_pathlib_module = fake_pathlib.FakePathlibModule(filesystem)`
-  `path = fake_pathlib_module.Path('/foo/bar')`
+If using `fake_filesystem_unittest.TestCase`, pytest fs fixture,
+or directly `Patcher`, pathlib gets replaced
+by fake_pathlib together with other file system related modules.
 
 Note: as the implementation is based on FakeFilesystem, all faked classes
 (including PurePosixPath, PosixPath, PureWindowsPath and WindowsPath)
@@ -867,11 +861,6 @@ class FakePathlibModule:
 
     Automatically created if using `fake_filesystem_unittest.TestCase`,
     the `fs` fixture, the `patchfs` decorator, or directly the `Patcher`.
-
-    For creating it separately, a `fake_filesystem` instance is needed::
-
-        filesystem = fake_filesystem.FakeFilesystem()
-        fake_pathlib_module = fake_pathlib.FakePathlibModule(filesystem)
     """
 
     def __init__(self, filesystem, from_patcher=False):

pyfakefs/tests/fake_filesystem_test.py

@@ -1045,7 +1045,7 @@ def test_realpath_allow_missing(self):
         root_dir = self.filesystem.root_dir_name
         self.filesystem.cwd = f"{root_dir}foo"
         self.assertEqual(
-            "!foo!baz",
+            f"{root_dir}foo!baz",
             self.os.path.realpath("baz", strict=os.path.ALLOW_MISSING),  # type: ignore[attr-defined]
         )
         if not is_root():