bpo-31163: Added return values to pathlib.Path instance's rename and replace methods. (GH-13582)

* bpo-31163: Added return values to pathlib.Path instance's rename and replace methods.

Doc/library/pathlib.rst

@@ -946,23 +946,32 @@ call fails (for example because the path doesn't exist).
 
 .. method:: Path.rename(target)
 
-   Rename this file or directory to the given *target*.  On Unix, if
+   Rename this file or directory to the given *target*, and return a new Path
-   *target* exists and is a file, it will be replaced silently if the user
+   instance pointing to *target*.  On Unix, if *target* exists and is a file,
-   has permission.  *target* can be either a string or another path object::
+   it will be replaced silently if the user has permission.  *target* can be
+   either a string or another path object::
 
       >>> p = Path('foo')
       >>> p.open('w').write('some text')
       9
       >>> target = Path('bar')
       >>> p.rename(target)
+      PosixPath('bar')
       >>> target.open().read()
       'some text'
 
+   .. versionchanged:: 3.8
+      Added return value, return the new Path instance.
+
 
 .. method:: Path.replace(target)
 
-   Rename this file or directory to the given *target*.  If *target* points
+   Rename this file or directory to the given *target*, and return a new Path
-   to an existing file or directory, it will be unconditionally replaced.
+   instance pointing to *target*.  If *target* points to an existing file or
+   directory, it will be unconditionally replaced.
+
+   .. versionchanged:: 3.8
+      Added return value, return the new Path instance.
 
 
 .. method:: Path.resolve(strict=False)

Lib/pathlib.py

@@ -1341,20 +1341,24 @@ class Path(PurePath):
 
     def rename(self, target):
         """
-        Rename this path to the given path.
+        Rename this path to the given path,
+        and return a new Path instance pointing to the given path.
         """
         if self._closed:
             self._raise_closed()
         self._accessor.rename(self, target)
+        return self.__class__(target)
 
     def replace(self, target):
         """
         Rename this path to the given path, clobbering the existing
-        destination if it exists.
+        destination if it exists, and return a new Path instance
+        pointing to the given path.
         """
         if self._closed:
             self._raise_closed()
         self._accessor.replace(self, target)
+        return self.__class__(target)
 
     def symlink_to(self, target, target_is_directory=False):
         """

Lib/test/test_pathlib.py

@@ -1767,12 +1767,14 @@ class _BasePathTest(object):
         size = p.stat().st_size
         # Renaming to another path.
         q = P / 'dirA' / 'fileAA'
-        p.rename(q)
+        renamed_p = p.rename(q)
+        self.assertEqual(renamed_p, q)
         self.assertEqual(q.stat().st_size, size)
         self.assertFileNotFound(p.stat)
         # Renaming to a str of a relative path.
         r = rel_join('fileAAA')
-        q.rename(r)
+        renamed_q = q.rename(r)
+        self.assertEqual(renamed_q, self.cls(r))
         self.assertEqual(os.stat(r).st_size, size)
         self.assertFileNotFound(q.stat)
 
@@ -1782,12 +1784,14 @@ class _BasePathTest(object):
         size = p.stat().st_size
         # Replacing a non-existing path.
         q = P / 'dirA' / 'fileAA'
-        p.replace(q)
+        replaced_p = p.replace(q)
+        self.assertEqual(replaced_p, q)
         self.assertEqual(q.stat().st_size, size)
         self.assertFileNotFound(p.stat)
         # Replacing another (existing) path.
         r = rel_join('dirB', 'fileB')
-        q.replace(r)
+        replaced_q = q.replace(r)
+        self.assertEqual(replaced_q, self.cls(r))
         self.assertEqual(os.stat(r).st_size, size)
         self.assertFileNotFound(q.stat)
 

Misc/NEWS.d/next/Library/2019-05-26-16-34-53.bpo-31163.21A802.rst

@@ -0,0 +1,2 @@
+pathlib.Path instance's rename and replace methods now return the new Path
+instance.