Move shutil patches to fake shutil module

mrbean-bremen · mrbean-bremen · commit bcd91d11d559 · 2025-06-15T21:44:04.000+02:00
- allows to use FakeShutilModule outside of Patcher
diff --git a/CHANGES.md b/CHANGES.md
@@ -17,6 +17,8 @@ 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
+  (see [#1171](../../discussions/1171))
 
 ### Enhancements
 * added convenience function `add_package_metadata` to add the metadata of a given
diff --git a/pyfakefs/fake_filesystem_shutil.py b/pyfakefs/fake_filesystem_shutil.py
@@ -22,11 +22,26 @@
     shutil module.
 
 :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")
+
 """
 
+import contextlib
 import os
 import shutil
 import sys
@@ -35,8 +50,28 @@
 class FakeShutilModule:
     """Uses a FakeFilesystem to provide a fake replacement
     for shutil module.
+
+    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")
     """
 
+    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]
+
     @staticmethod
     def dir():
         """Return the list of patched function names. Used for patching
@@ -51,7 +86,46 @@ def __init__(self, filesystem):
           filesystem:  FakeFilesystem used to provide file system information
         """
         self.filesystem = filesystem
-        self._shutil_module = shutil
+        self.shutil_module = shutil
+        self._in_get_attribute = False
+
+    def start_patching_global_vars(self):
+        if self.__class__.has_fcopy_file:
+            self.shutil_module._HAS_FCOPYFILE = False
+        if self.__class__.use_copy_file_range:
+            self.shutil_module._USE_CP_COPY_FILE_RANGE = False
+        if self.__class__.use_sendfile:
+            self.shutil_module._USE_CP_SENDFILE = False
+        if self.use_fd_functions:
+            if sys.version_info >= (3, 14):
+                self.shutil_module._rmtree_impl = (
+                    self.shutil_module._rmtree_unsafe  # type: ignore[attr-defined]
+                )
+            else:
+                self.shutil_module._use_fd_functions = False
+
+    def stop_patching_global_vars(self):
+        if self.__class__.has_fcopy_file:
+            self.shutil_module._HAS_FCOPYFILE = True
+        if self.__class__.use_copy_file_range:
+            self.shutil_module._USE_CP_COPY_FILE_RANGE = True
+        if self.__class__.use_sendfile:
+            self.shutil_module._USE_CP_SENDFILE = True
+        if self.__class__.use_fd_functions:
+            if sys.version_info >= (3, 14):
+                self.__class__.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 disk_usage(self, path):
         """Return the total, used and free disk space in bytes as named tuple
@@ -62,6 +136,32 @@ 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):
@@ -89,7 +189,7 @@ def copytree(
             """Make sure the default argument is patched."""
             if copy_function == shutil.copy2:
                 copy_function = self.copy2
-            return self._shutil_module.copytree(
+            return self.shutil_module.copytree(
                 src,
                 dst,
                 symlinks,
@@ -103,8 +203,8 @@ def move(self, src, dst, copy_function=shutil.copy2):
             """Make sure the default argument is patched."""
             if copy_function == shutil.copy2:
                 copy_function = self.copy2
-            return self._shutil_module.move(src, dst, copy_function)
+            return self.shutil_module.move(src, dst, copy_function)
 
     def __getattr__(self, name):
         """Forwards any non-faked calls to the standard shutil module."""
-        return getattr(self._shutil_module, name)
+        return getattr(self.shutil_module, name)
diff --git a/pyfakefs/fake_filesystem_unittest.py b/pyfakefs/fake_filesystem_unittest.py
@@ -45,7 +45,6 @@
 import io
 import linecache
 import os
-import shutil
 import sys
 import tempfile
 import tokenize
@@ -690,6 +689,20 @@ def __init__(
         self.use_dynamic_patch = use_dynamic_patch
         self.cleanup_handlers: Dict[str, Callable[[str], bool]] = {}
 
+        # Attributes set by _refresh()
+        self._stubs: Optional[StubOutForTesting] = None
+        self.fs: Optional[FakeFilesystem] = None
+        self.fake_modules: Dict[str, Any] = {}
+        self.unfaked_modules: Dict[str, Any] = {}
+
+        # _isStale is set by tearDown(), reset by _refresh()
+        self._isStale = True
+        self._dyn_patcher: Optional[DynamicPatcher] = None
+        self._patching = False
+        self._paused = False
+        self.has_copy_file_range = False
+        self.has_copy_file = False
+
         if use_known_patches:
             from pyfakefs.patched_packages import (
                 get_modules_to_patch,
@@ -727,20 +740,6 @@ def __init__(
         self._fake_module_functions: Dict[str, Dict] = {}
         self._init_fake_module_functions()
 
-        # Attributes set by _refresh()
-        self._stubs: Optional[StubOutForTesting] = None
-        self.fs: Optional[FakeFilesystem] = None
-        self.fake_modules: Dict[str, Any] = {}
-        self.unfaked_modules: Dict[str, Any] = {}
-
-        # _isStale is set by tearDown(), reset by _refresh()
-        self._isStale = True
-        self._dyn_patcher: Optional[DynamicPatcher] = None
-        self._patching = False
-        self._paused = False
-        self.has_copy_file_range = False
-        self.has_copy_file = False
-
     @classmethod
     def clear_fs_cache(cls) -> None:
         """Clear the module cache."""
@@ -1027,30 +1026,6 @@ def setUp(self, doctester: Any = None) -> None:
             self.__class__.REF_COUNT += 1
             if self.__class__.REF_COUNT > 1:
                 return
-        self.has_fcopy_file = (
-            sys.platform == "darwin"
-            and hasattr(shutil, "_HAS_FCOPYFILE")
-            and shutil._HAS_FCOPYFILE
-        )
-        if self.has_fcopy_file:
-            shutil._HAS_FCOPYFILE = False  # type: ignore[attr-defined]
-
-        self.has_copy_file_range = (
-            sys.platform == "linux"
-            and hasattr(shutil, "_USE_CP_COPY_FILE_RANGE")
-            and shutil._USE_CP_COPY_FILE_RANGE
-        )
-        if self.has_copy_file_range:
-            shutil._USE_CP_COPY_FILE_RANGE = False  # type: ignore[attr-defined]
-
-        # do not use the fd functions, as they may not be available in the target OS
-        if hasattr(shutil, "_use_fd_functions"):
-            shutil._use_fd_functions = False  # type: ignore[module-attr]
-        # in Python 3.14, _rmtree_impl is set at load time based on _use_fd_functions
-        # the safe version cannot be used at the moment as it used asserts of type
-        # 'assert func is os.rmtree', which do not work with the fake versions
-        if hasattr(shutil, "_rmtree_impl"):
-            shutil._rmtree_impl = shutil._rmtree_unsafe  # type: ignore[attr-defined]
 
         with warnings.catch_warnings():
             # ignore warnings, see #542 and #614
@@ -1169,10 +1144,6 @@ def tearDown(self, doctester: Any = None):
             if self.__class__.REF_COUNT > 0:
                 return
         self.stop_patching()
-        if self.has_fcopy_file:
-            shutil._HAS_FCOPYFILE = True  # type: ignore[attr-defined]
-        if self.has_copy_file_range:
-            shutil._USE_CP_COPY_FILE_RANGE = True  # type: ignore[attr-defined]
 
         reset_ids()
         if self.is_doc_test:
diff --git a/pyfakefs/fake_pathlib.py b/pyfakefs/fake_pathlib.py
@@ -15,8 +15,9 @@
 
 Usage:
 
-* With fake_filesystem_unittest:
-  If using fake_filesystem_unittest.TestCase, pathlib gets replaced
+* 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:
@@ -865,7 +866,7 @@ class FakePathlibModule:
     """Uses FakeFilesystem to provide a fake pathlib module replacement.
 
     Automatically created if using `fake_filesystem_unittest.TestCase`,
-    `fs` fixture, or the `patchfs` decorator.
+    the `fs` fixture, the `patchfs` decorator, or directly the `Patcher`.
 
     For creating it separately, a `fake_filesystem` instance is needed::
 
