GH-73991: Add pathlib.Path.move()

Add a `Path.move()` method that moves a file or directory tree and returns a new `Path` instance. This method is similar to `shutil.move()`, except that it doesn't accept a *copy_function* argument, and it doesn't support copying into an existing directory.
python · barneygale · Aug 25, 2024 · Jul 21, 2024 · Jul 21, 2024 · Jul 21, 2024
commit f6d09c0d450eaf929373eb19a161c88115598bbb
@@ -1536,8 +1536,8 @@ Creating files and directories
       available. In previous versions, :exc:`NotImplementedError` was raised.
 
 
-Copying, renaming and deleting
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Copying, moving and deleting
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. method:: Path.copy(target, *, follow_symlinks=True, preserve_metadata=False)
 
@@ -1592,6 +1592,18 @@ Copying, renaming and deleting
    .. versionadded:: 3.14
 
 
+.. method:: Path.move(target)
+
+   Recursively move this file or directory tree to the given *target*, and
+   return a new :class:`!Path` instance pointing to *target*.
+
+   If both paths are on the same filesystem, the move is performed with
+   :func:`os.rename`. Otherwise, this path is copied (preserving metadata and
+   symlinks) and then deleted.
+
+   .. versionadded:: 3.14
+
+
 .. method:: Path.rename(target)
 
    Rename this file or directory to the given *target*, and return a new

@@ -118,14 +118,17 @@ os
 pathlib
 -------
 
-* Add methods to :class:`pathlib.Path` to recursively copy or remove files:
+* Add methods to :class:`pathlib.Path` to recursively copy, move, or remove
+  files and directories:
 
   * :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`.
+  * :meth:`~pathlib.Path.move` moves a file or directory tree, like
+    :func:`shutil.move`.
 
   (Contributed by Barney Gale in :gh:`73991`.)
 

@@ -846,6 +846,11 @@ def copytree(self, target, *, follow_symlinks=True,
         if on_error is None:
             def on_error(err):
                 raise err
+        if target.is_relative_to(self):
+            try:
+                raise OSError(f"Cannot copy {self!r} inside itself: {target!r}")
+            except OSError as err:
+                on_error(err)
         stack = [(self, target)]
         while stack:
             source_dir, target_dir = stack.pop()
@@ -869,6 +874,22 @@ def on_error(err):
             except OSError as err:
                 on_error(err)
 
+    def move(self, target):
+        """
+        Recursively move this file or directory tree to the given destination.
+        """
+        if not isinstance(target, PathBase):
+            target = self.with_segments(target)
+        if self.is_dir(follow_symlinks=False):
+            copy_self = self.copytree
+            delete_self = self.rmtree
+        else:
+            copy_self = self.copy
+            delete_self = self.unlink
+        copy_self(target, follow_symlinks=False, preserve_metadata=True)
+        delete_self()
+        return target
+
     def rename(self, target):
         """
         Rename this path to the target path.

diff --git a/Lib/pathlib/_local.py b/Lib/pathlib/_local.py
@@ -1,3 +1,4 @@
+import errno
 import io
 import ntpath
 import operator
@@ -849,6 +850,23 @@ def onexc(func, filename, err):
         import shutil
         shutil.rmtree(str(self), ignore_errors, onexc=onexc)
 
+    def move(self, target):
+        """
+        Recursively move this file or directory tree to the given destination.
+        """
+
+        try:
+            target = self.with_segments(target)
+            os.rename(self, target)
+            return target
+        except TypeError:
+            if not isinstance(target, PathBase):
+                raise
+        except OSError as err:
+            if err.errno != errno.EXDEV:
+                raise
+        return PathBase.move(self, target)
+
     def rename(self, target):
         """
         Rename this path to the target path.

@@ -1980,6 +1980,75 @@ def test_copytree_dangling_symlink(self):
         self.assertTrue(target2.joinpath('link').is_symlink())
         self.assertEqual(target2.joinpath('link').readlink(), self.cls('nonexistent'))
 
+    def test_move_file(self):
+        base = self.cls(self.base)
+        source = base / 'fileA'
+        source_text = source.read_text()
+        target = base / 'fileA_moved'
+        result = source.move(target)
+        self.assertEqual(result, target)
+        self.assertFalse(source.exists())
+        self.assertTrue(target.exists())
+        self.assertEqual(source_text, target.read_text())
+
+    def test_move_dir(self):
+        base = self.cls(self.base)
+        source = base / 'dirC'
+        target = base / 'dirC_moved'
+        result = source.move(target)
+        self.assertEqual(result, target)
+        self.assertFalse(source.exists())
+        self.assertTrue(target.is_dir())
+        self.assertTrue(target.joinpath('dirD').is_dir())
+        self.assertTrue(target.joinpath('dirD', 'fileD').is_file())
+        self.assertEqual(target.joinpath('dirD', 'fileD').read_text(),
+                         "this is file D\n")
+        self.assertTrue(target.joinpath('fileC').is_file())
+        self.assertTrue(target.joinpath('fileC').read_text(),
+                        "this is file C\n")
+
+    def test_move_dir_into_itself(self):
+        base = self.cls(self.base)
+        source = base / 'dirC'
+        target = base / 'dirC' / 'bar'
+        self.assertRaises(OSError, source.move, target)
+
+    @needs_symlinks
+    def test_move_file_symlink(self):
+        base = self.cls(self.base)
+        source = base / 'linkA'
+        source_readlink = source.readlink()
+        target = base / 'linkA_moved'
+        result = source.move(target)
+        self.assertEqual(result, target)
+        self.assertFalse(source.exists())
+        self.assertTrue(target.is_symlink())
+        self.assertEqual(source_readlink, target.readlink())
+
+    @needs_symlinks
+    def test_move_directory_symlink(self):
+        base = self.cls(self.base)
+        source = base / 'linkB'
+        source_readlink = source.readlink()
+        target = base / 'linkB_moved'
+        result = source.move(target)
+        self.assertEqual(result, target)
+        self.assertFalse(source.exists())
+        self.assertTrue(target.is_symlink())
+        self.assertEqual(source_readlink, target.readlink())
+
+    @needs_symlinks
+    def test_move_dangling_symlink(self):
+        base = self.cls(self.base)
+        source = base / 'brokenLink'
+        source_readlink = source.readlink()
+        target = base / 'brokenLink_moved'
+        result = source.move(target)
+        self.assertEqual(result, target)
+        self.assertFalse(source.exists())
+        self.assertTrue(target.is_symlink())
+        self.assertEqual(source_readlink, target.readlink())
+
     def test_iterdir(self):
         P = self.cls
         p = P(self.base)

diff --git a/Misc/NEWS.d/next/Library/2024-07-21-02-00-46.gh-issue-73991.pLxdtJ.rst b/Misc/NEWS.d/next/Library/2024-07-21-02-00-46.gh-issue-73991.pLxdtJ.rst
@@ -0,0 +1 @@
+Add :meth:`pathlib.Path.move`, which moves a file or directory tree.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Add :meth:`pathlib.Path.move`, which moves a file or directory tree.