From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Mon, 6 Jul 2026 17:23:15 +0000 (+0200)
Subject: [3.15] gh-150880: Clarify DirEntry.path construction semantics (GH-153218) (GH-153219)
X-Git-Tag: v3.15.0b4~97
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=9d603d3c12b8365ef2db26746ec1f21855c98927;p=thirdparty%2FPython%2Fcpython.git

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

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 fba6ece80e5d..7dd2333d8dc7 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -3037,10 +3037,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.