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

[Jason R. Coombs]

https://github.com/python/cpython/commit/cbd7b2a399a8ff2ed9994c380b07ef598892b6b1
commit: cbd7b2a399a8ff2ed9994c380b07ef598892b6b1
branch: 3.8
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: Jason R. Coombs <jaraco at jaraco.com>
date: 2019-09-11T15:12:54+01:00
summary:

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

* 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 at gmail.com>

files:
A Misc/NEWS.d/next/Library/2019-05-26-16-34-53.bpo-31163.21A802.rst
M Doc/library/pathlib.rst
M Lib/pathlib.py
M Lib/test/test_pathlib.py

diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index 166de8de1f06..ad8f6011ad02 100644
--- 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 6355ae864108..91ce4a125740 100644
--- a/Lib/pathlib.py
+++ b/Lib/pathlib.py
@@ -1332,20 +1332,24 @@ def link_to(self, target):
 
     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 027331f95911..ebc71ec219c8 100644
--- a/Lib/test/test_pathlib.py
+++ b/Lib/test/test_pathlib.py
@@ -1680,12 +1680,14 @@ def test_rename(self):
         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 @@ def test_replace(self):
         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
index 000000000000..6ec074612141
--- /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.