GH-73991: Add pathlib.Path.rmtree() (#119060)

Add a `Path.rmtree()` method that removes an entire directory tree, like
`shutil.rmtree()`. The signature of the optional *on_error* argument
matches the `Path.walk()` argument of the same name, but differs from the
*onexc* and *onerror* arguments to `shutil.rmtree()`. Consistency within
pathlib is probably more important.

In the private pathlib ABCs, we add an implementation based on `walk()`.

Co-authored-by: Bénédikt Tran <[email protected]>

Author: barneygale

Doc/library/pathlib.rst

@@ -1645,6 +1645,34 @@ Copying, renaming and deleting
    Remove this directory.  The directory must be empty.
 
 
+.. method:: Path.rmtree(ignore_errors=False, on_error=None)
+
+   Recursively delete this entire directory tree. The path must not refer to a symlink.
+
+   If *ignore_errors* is true, errors resulting from failed removals will be
+   ignored. If *ignore_errors* is false or omitted, and a function is given to
+   *on_error*, it will be called each time an exception is raised. If neither
+   *ignore_errors* nor *on_error* are supplied, exceptions are propagated to
+   the caller.
+
+   .. note::
+
+      On platforms that support the necessary fd-based functions, a symlink
+      attack-resistant version of :meth:`~Path.rmtree` is used by default. On
+      other platforms, the :func:`~Path.rmtree` implementation is susceptible
+      to a symlink attack: given proper timing and circumstances, attackers
+      can manipulate symlinks on the filesystem to delete files they would not
+      be able to access otherwise.
+
+   If the optional argument *on_error* is specified, it should be a callable;
+   it will be called with one argument of type :exc:`OSError`. The
+   callable can handle the error to continue the deletion process or re-raise
+   it to stop. Note that the filename is available as the :attr:`~OSError.filename`
+   attribute of the exception object.
+
+   .. versionadded:: 3.14
+
+
 Permissions and ownership
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 

Doc/whatsnew/3.14.rst

@@ -118,11 +118,15 @@ os
 pathlib
 -------
 
-* Add :meth:`pathlib.Path.copy`, which copies the content of one file to
-  another, like :func:`shutil.copyfile`.
-  (Contributed by Barney Gale in :gh:`73991`.)
-* Add :meth:`pathlib.Path.copytree`, which copies one directory tree to
-  another.
+* Add methods to :class:`pathlib.Path` to recursively copy or remove files:
+
+  * :meth:`~pathlib.Path.copy` copies the content of one file to another, like
+    :func:`shutil.copyfile`.
+  * :meth:`~pathlib.Path.copytree` copies one directory tree to another, like
+    :func:`shutil.copytree`.
+  * :meth:`~pathlib.Path.rmtree` recursively removes a directory tree, like
+    :func:`shutil.rmtree`.
+
   (Contributed by Barney Gale in :gh:`73991`.)
 
 pdb

Lib/pathlib/_abc.py

@@ -915,6 +915,47 @@ def rmdir(self):
         """
         raise UnsupportedOperation(self._unsupported_msg('rmdir()'))
 
+    def rmtree(self, ignore_errors=False, on_error=None):
+        """
+        Recursively delete this directory tree.
+
+        If *ignore_errors* is true, exceptions raised from scanning the tree
+        and removing files and directories are ignored. Otherwise, if
+        *on_error* is set, it will be called to handle the error. If neither
+        *ignore_errors* nor *on_error* are set, exceptions are propagated to
+        the caller.
+        """
+        if ignore_errors:
+            def on_error(err):
+                pass
+        elif on_error is None:
+            def on_error(err):
+                raise err
+        try:
+            if self.is_symlink():
+                raise OSError("Cannot call rmtree on a symbolic link")
+            elif self.is_junction():
+                raise OSError("Cannot call rmtree on a junction")
+            results = self.walk(
+                on_error=on_error,
+                top_down=False,  # Bottom-up so we rmdir() empty directories.
+                follow_symlinks=False)
+            for dirpath, dirnames, filenames in results:
+                for name in filenames:
+                    try:
+                        dirpath.joinpath(name).unlink()
+                    except OSError as err:
+                        on_error(err)
+                for name in dirnames:
+                    try:
+                        dirpath.joinpath(name).rmdir()
+                    except OSError as err:
+                        on_error(err)
+            self.rmdir()
+        except OSError as err:
+            err.filename = str(self)
+            on_error(err)
+
     def owner(self, *, follow_symlinks=True):
         """
         Return the login name of the file owner.

Lib/pathlib/_local.py

@@ -830,6 +830,25 @@ def rmdir(self):
         """
         os.rmdir(self)
 
+    def rmtree(self, ignore_errors=False, on_error=None):
+        """
+        Recursively delete this directory tree.
+
+        If *ignore_errors* is true, exceptions raised from scanning the tree
+        and removing files and directories are ignored. Otherwise, if
+        *on_error* is set, it will be called to handle the error. If neither
+        *ignore_errors* nor *on_error* are set, exceptions are propagated to
+        the caller.
+        """
+        if on_error:
+            def onexc(func, filename, err):
+                err.filename = filename
+                on_error(err)
+        else:
+            onexc = None
+        import shutil
+        shutil.rmtree(str(self), ignore_errors, onexc=onexc)
+
     def rename(self, target):
         """
         Rename this path to the target path.