[3.13] gh-150880: Clarify DirEntry.path construction semantics (GH-153218) (GH-153221)

gh-150880: Clarify DirEntry.path construction semantics (GH-153218)
(cherry picked from commit 53661afabd2b4a9c92230ee7024dc42782164f8e)

Co-authored-by: Zain Nadeem <zainnadeemzainnadeem80@gmail.com>

diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 552494de970c0d8b0873fc28c050ce24fa8ec9f2..9b74ef35ec60eb4eea5b81a3c7e6e812cf872697 100644 (file)
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -2907,10 +2907,16 @@ features:
 
    .. attribute:: path
 
-      The entry's full path name: equivalent to ``os.path.join(scandir_path,
-      entry.name)`` where *scandir_path* is the :func:`scandir` *path*
-      argument.  The path is only absolute if the :func:`scandir` *path*
-      argument was absolute.  If the :func:`scandir` *path*
+      The entry's path name: equivalent to ``os.path.join(scandir_path,
+      entry.name)`` where *scandir_path* is the original :func:`scandir`
+      *path* argument.  Apart from the filename, the path preserves the
+      original :func:`scandir` argument.  If the :func:`scandir` *path*
+      argument was relative, the :attr:`path` attribute is also relative.
+      Changing the current working directory after creating the
+      :func:`scandir` iterator may cause later uses of :attr:`path` to resolve
+      differently.  On some platforms, the constructed path may not be valid
+      if the original :func:`scandir` argument was usable for enumeration but
+      not for joining with the entry name.  If the :func:`scandir` *path*
       argument was a :ref:`file descriptor <path_fd>`, the :attr:`path`
       attribute is the same as the :attr:`name` attribute.