pathlib ABCs: yield progress reports from WritablePath._copy_from()

Make `WritablePath._copy_from()` yield `(target, source, part_size)`
tuples when copying files and directories. A tuple with `part_size=0` is
emitted for every path encountered, and further tuples with `part_size>0`
**may** be emitted when copying regular files.

This should allow `anyio.Path` to wrap `_copy_from()` and make it
cancelable.

Author: barneygale

Lib/pathlib/__init__.py

@@ -1109,7 +1109,7 @@ def copy(self, target, **kwargs):
             copy_to_target = target._copy_from
         except AttributeError:
             raise TypeError(f"Target path is not writable: {target!r}") from None
-        copy_to_target(self, **kwargs)
+        list(copy_to_target(self, **kwargs))  # Consume generator.
         return target.joinpath()  # Empty join to ensure fresh metadata.
 
     def copy_into(self, target_dir, **kwargs):
@@ -1127,26 +1127,30 @@ def copy_into(self, target_dir, **kwargs):
 
     def _copy_from(self, source, follow_symlinks=True, preserve_metadata=False):
         """
-        Recursively copy the given path to this path.
+        Recursively copy the given path to this path. This a generator
+        function that yields (target, source, part_size) tuples as the copying
+        operation progresses.
         """
+        yield self, source, 0
         if not follow_symlinks and source.info.is_symlink():
             self._copy_from_symlink(source, preserve_metadata)
         elif source.info.is_dir():
             children = source.iterdir()
             os.mkdir(self)
             for child in children:
-                self.joinpath(child.name)._copy_from(
+                yield from self.joinpath(child.name)._copy_from(
                     child, follow_symlinks, preserve_metadata)
             if preserve_metadata:
                 copy_info(source.info, self)
         else:
-            self._copy_from_file(source, preserve_metadata)
+            for part_size in self._copy_from_file(source, preserve_metadata):
+                yield self, source, part_size
 
     def _copy_from_file(self, source, preserve_metadata=False):
         ensure_different_files(source, self)
         with magic_open(source, 'rb') as source_f:
             with open(self, 'wb') as target_f:
-                copyfileobj(source_f, target_f)
+                yield from copyfileobj(source_f, target_f)
         if preserve_metadata:
             copy_info(source.info, self)
 
@@ -1160,8 +1164,8 @@ def _copy_from_file(self, source, preserve_metadata=False):
                 pass
             else:
                 copyfile2(source, str(self))
-                return
-            self._copy_from_file_fallback(source, preserve_metadata)
+                return iter([])
+            return self._copy_from_file_fallback(source, preserve_metadata)
 
     if os.name == 'nt':
         # If a directory-symlink is copied *before* its target, then

Lib/pathlib/_os.py

@@ -163,7 +163,7 @@ def copyfileobj(source_f, target_f):
     read_source = source_f.read
     write_target = target_f.write
     while buf := read_source(1024 * 1024):
-        write_target(buf)
+        yield write_target(buf)
 
 
 def magic_open(path, mode='r', buffering=-1, encoding=None, errors=None,

Lib/pathlib/types.py

@@ -343,7 +343,7 @@ def copy(self, target, **kwargs):
             copy_to_target = target._copy_from
         except AttributeError:
             raise TypeError(f"Target path is not writable: {target!r}") from None
-        copy_to_target(self, **kwargs)
+        list(copy_to_target(self, **kwargs))  # Consume generator.
         return target.joinpath()  # Empty join to ensure fresh metadata.
 
     def copy_into(self, target_dir, **kwargs):
@@ -413,23 +413,27 @@ def write_text(self, data, encoding=None, errors=None, newline=None):
 
     def _copy_from(self, source, follow_symlinks=True):
         """
-        Recursively copy the given path to this path.
+        Recursively copy the given path to this path. This a generator
+        function that yields (target, source, part_size) tuples as the copying
+        operation progresses.
         """
-        stack = [(source, self)]
+        stack = [(self, source)]
         while stack:
-            src, dst = stack.pop()
+            dst, src = stack.pop()
+            yield dst, src, 0
             if not follow_symlinks and src.info.is_symlink():
                 dst.symlink_to(str(src.readlink()), src.info.is_dir())
             elif src.info.is_dir():
                 children = src.iterdir()
                 dst.mkdir()
                 for child in children:
-                    stack.append((child, dst.joinpath(child.name)))
+                    stack.append((dst.joinpath(child.name), child))
             else:
                 ensure_different_files(src, dst)
                 with magic_open(src, 'rb') as source_f:
                     with magic_open(dst, 'wb') as target_f:
-                        copyfileobj(source_f, target_f)
+                        for part_size in copyfileobj(source_f, target_f):
+                            yield dst, src, part_size
 
 
 _JoinablePath.register(PurePath)