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

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

diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index 33fac5f6972583e7db841857e3e0cf54e62ff16e..d33e2d0c89b1f45c436c452a9a3bb52421def2bb 100644 (file)
--- a/Doc/library/pathlib.rst
+++ b/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
-   *target* exists and is a file, it will be replaced silently if the user
-   has permission.  *target* can be either a string or another path object::
+   Rename this file or directory to the given *target*, and return a new Path
+   instance pointing to *target*.  On Unix, if *target* exists and is a file,
+   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
-   to an existing file or directory, it will be unconditionally replaced.
+   Rename this file or directory to the given *target*, and return a new Path
+   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)

diff --git a/Lib/pathlib.py b/Lib/pathlib.py
index 80923c768268fcd7b1faae0c1b75a28e7e537186..7bd66c10cbdb647e6d1e52e7442093048769956d 100644 (file)
--- a/Lib/pathlib.py
+++ b/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):
         """

diff --git a/Lib/test/test_pathlib.py b/Lib/test/test_pathlib.py
index 34c66f3137ff08acd6908ecb2b81704757ff504e..f3b385fbf36721a6686848f9f228d7ceeebb1479 100644 (file)
--- a/Lib/test/test_pathlib.py
+++ b/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)
 

diff --git a/Misc/NEWS.d/next/Library/2019-05-26-16-34-53.bpo-31163.21A802.rst b/Misc/NEWS.d/next/Library/2019-05-26-16-34-53.bpo-31163.21A802.rst
new file mode 100644 (file)
index 0000000..6ec0746
--- /dev/null
+++ b/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.