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.
(cherry picked from commit 088a09af4bdeff52b9dedeb7acd1e82069f37d98)

Co-authored-by: hui shang <shangdahao@gmail.com>

diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index 166de8de1f062e58dca62a8e9e9fc3abee1fc9c3..ad8f6011ad02f9139992bb175b705529577b0b2f 100644 (file)
--- a/Doc/library/pathlib.rst
+++ b/Doc/library/pathlib.rst
@@ -933,23 +933,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 6355ae86410853941e5153ba08762c91d54ce825..91ce4a125740af28e7cd5804ad2c7dcbee6fc9a6 100644 (file)
--- a/Lib/pathlib.py
+++ b/Lib/pathlib.py
@@ -1332,20 +1332,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 027331f95911e86d68fbc85c33f925662db03cb9..ebc71ec219c8db347c801744a14a20234a194b1b 100644 (file)
--- a/Lib/test/test_pathlib.py
+++ b/Lib/test/test_pathlib.py
@@ -1680,12 +1680,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)
 
@@ -1695,12 +1697,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.