From: Miss Skeleton (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Sat, 3 Oct 2020 10:11:39 +0000 (-0700)
Subject: bpo-40833: Clarify Path.rename doc-string regarding relative paths (GH-20554)
X-Git-Tag: v3.8.7rc1~142
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=4b982e0dd7354c9103a0cae8e6e78b5e57794e77;p=thirdparty%2FPython%2Fcpython.git

bpo-40833: Clarify Path.rename doc-string regarding relative paths (GH-20554)

(cherry picked from commit f97e42ef4d97dee64f45ed65170a6e77c8e46fdf)

Co-authored-by: Ram Rachum <ram@rachum.com>
---

diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index c855a6e11dac..4518f5600492 100644
--- a/Doc/library/pathlib.rst
+++ b/Doc/library/pathlib.rst
@@ -954,6 +954,10 @@ call fails (for example because the path doesn't exist).
       >>> target.open().read()
       'some text'
 
+   The target path may be absolute or relative. Relative paths are interpreted
+   relative to the current working directory, *not* the directory of the Path
+   object.
+
    .. versionchanged:: 3.8
       Added return value, return the new Path instance.
 
@@ -964,6 +968,10 @@ call fails (for example because the path doesn't exist).
    instance pointing to *target*.  If *target* points to an existing file or
    directory, it will be unconditionally replaced.
 
+   The target path may be absolute or relative. Relative paths are interpreted
+   relative to the current working directory, *not* the directory of the Path
+   object.
+
    .. versionchanged:: 3.8
       Added return value, return the new Path instance.
 
diff --git a/Lib/pathlib.py b/Lib/pathlib.py
index 4f72bab3bdbb..171d8b825210 100644
--- a/Lib/pathlib.py
+++ b/Lib/pathlib.py
@@ -1353,8 +1353,13 @@ class Path(PurePath):
 
     def rename(self, target):
         """
-        Rename this path to the given path,
-        and return a new Path instance pointing to the given path.
+        Rename this path to the target path.
+
+        The target path may be absolute or relative. Relative paths are
+        interpreted relative to the current working directory, *not* the
+        directory of the Path object.
+
+        Returns the new Path instance pointing to the target path.
         """
         if self._closed:
             self._raise_closed()
@@ -1363,9 +1368,13 @@ class Path(PurePath):
 
     def replace(self, target):
         """
-        Rename this path to the given path, clobbering the existing
-        destination if it exists, and return a new Path instance
-        pointing to the given path.
+        Rename this path to the target path, overwriting if that path exists.
+
+        The target path may be absolute or relative. Relative paths are
+        interpreted relative to the current working directory, *not* the
+        directory of the Path object.
+
+        Returns the new Path instance pointing to the target path.
         """
         if self._closed:
             self._raise_closed()