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

miss-islington · zainnadeem786 · web-flow · commit d87ee02499dd · 2026-07-06T18:22:05.000+01:00
gh-150880: Clarify DirEntry.path construction semantics (GH-153218) (cherry picked from commit 53661af) Co-authored-by: Zain Nadeem <zainnadeemzainnadeem80@gmail.com>
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
@@ -2980,10 +2980,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.
 
