From ccb103f81d53e9df09ae96669a1b222f7e2c0993 Mon Sep 17 00:00:00 2001 From: hauntsaninja Date: Fri, 6 Jan 2023 13:00:55 -0800 Subject: [PATCH 1/6] gh-100783: fix os.path.join documentation - Use "drive", not "drive letter", because of UNC paths - Previous components are not thrown away from relative drive letters - Use "segment" instead of "component" for consistency with pathlib See issue for more details --- Doc/library/os.path.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst index 50e089653fe71b..fe8a4b6bdcf508 100644 --- a/Doc/library/os.path.rst +++ b/Doc/library/os.path.rst @@ -306,17 +306,17 @@ the :mod:`glob` module.) .. function:: join(path, *paths) - Join one or more path components intelligently. The return value is the + Join one or more path segments intelligently. The return value is the concatenation of *path* and any members of *\*paths* with exactly one directory separator following each non-empty part except the last, meaning that the result will only end in a separator if the last part is empty. If - a component is an absolute path, all previous components are thrown away - and joining continues from the absolute path component. + a segment is an absolute path, all previous segments are ignored + and joining continues from the absolute path segment. - On Windows, the drive letter is not reset when an absolute path component - (e.g., ``r'\foo'``) is encountered. If a component contains a drive - letter, all previous components are thrown away and the drive letter is - reset. Note that since there is a current directory for each drive, + On Windows, the drive is not reset when a rooted path segment (e.g., + ``r'\foo'``) is encountered. If a segment is from a different drive or is an + absolute path, all previous segments are ignored and the drive is reset. Note + that since there is a current directory for each drive, ``os.path.join("c:", "foo")`` represents a path relative to the current directory on drive :file:`C:` (:file:`c:foo`), not :file:`c:\\foo`. From 5a3589b8fa54d4c8dae8b2596c055010f5c53b26 Mon Sep 17 00:00:00 2001 From: hauntsaninja Date: Fri, 6 Jan 2023 14:44:10 -0800 Subject: [PATCH 2/6] clarify "absolute" --- Doc/library/os.path.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst index fe8a4b6bdcf508..6c0532204f3a49 100644 --- a/Doc/library/os.path.rst +++ b/Doc/library/os.path.rst @@ -310,8 +310,9 @@ the :mod:`glob` module.) concatenation of *path* and any members of *\*paths* with exactly one directory separator following each non-empty part except the last, meaning that the result will only end in a separator if the last part is empty. If - a segment is an absolute path, all previous segments are ignored - and joining continues from the absolute path segment. + a segment is an absolute path (which on Windows requires both a drive and a + root), then all previous segments are ignored and joining continues from the + absolute path segment. On Windows, the drive is not reset when a rooted path segment (e.g., ``r'\foo'``) is encountered. If a segment is from a different drive or is an From 8c3acbff3b87968602fc907f177707c0e57189fc Mon Sep 17 00:00:00 2001 From: hauntsaninja Date: Fri, 6 Jan 2023 14:44:29 -0800 Subject: [PATCH 3/6] change preposition --- Doc/library/os.path.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst index 6c0532204f3a49..c6f4c62e935348 100644 --- a/Doc/library/os.path.rst +++ b/Doc/library/os.path.rst @@ -315,7 +315,7 @@ the :mod:`glob` module.) absolute path segment. On Windows, the drive is not reset when a rooted path segment (e.g., - ``r'\foo'``) is encountered. If a segment is from a different drive or is an + ``r'\foo'``) is encountered. If a segment is on a different drive or is an absolute path, all previous segments are ignored and the drive is reset. Note that since there is a current directory for each drive, ``os.path.join("c:", "foo")`` represents a path relative to the current From a2a6c81259f6194ddd2de43a6b14eb983b8932bc Mon Sep 17 00:00:00 2001 From: Shantanu <12621235+hauntsaninja@users.noreply.github.com> Date: Sat, 7 Jan 2023 15:51:04 -0800 Subject: [PATCH 4/6] Update Doc/library/os.path.rst --- Doc/library/os.path.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst index c6f4c62e935348..68f7dc4978760b 100644 --- a/Doc/library/os.path.rst +++ b/Doc/library/os.path.rst @@ -307,7 +307,7 @@ the :mod:`glob` module.) .. function:: join(path, *paths) Join one or more path segments intelligently. The return value is the - concatenation of *path* and any members of *\*paths* with exactly one + concatenation of *path* and all members of *\*paths*, with exactly one directory separator following each non-empty part except the last, meaning that the result will only end in a separator if the last part is empty. If a segment is an absolute path (which on Windows requires both a drive and a From 47294420f42f1cfb6026ff3e7876c646f6c915a1 Mon Sep 17 00:00:00 2001 From: Shantanu <12621235+hauntsaninja@users.noreply.github.com> Date: Sat, 7 Jan 2023 15:54:47 -0800 Subject: [PATCH 5/6] Update Doc/library/os.path.rst --- Doc/library/os.path.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst index 68f7dc4978760b..04d0c8b7da3439 100644 --- a/Doc/library/os.path.rst +++ b/Doc/library/os.path.rst @@ -309,7 +309,7 @@ the :mod:`glob` module.) Join one or more path segments intelligently. The return value is the concatenation of *path* and all members of *\*paths*, with exactly one directory separator following each non-empty part except the last, meaning - that the result will only end in a separator if the last part is empty. If + that the result will end in a separator if the last part is empty. If a segment is an absolute path (which on Windows requires both a drive and a root), then all previous segments are ignored and joining continues from the absolute path segment. From 403ef6e09f38ef5e3a9bdb7dfba8a4425ba76e4a Mon Sep 17 00:00:00 2001 From: hauntsaninja Date: Sat, 7 Jan 2023 16:21:33 -0800 Subject: [PATCH 6/6] split sentences --- Doc/library/os.path.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst index 04d0c8b7da3439..42bbe24830e6c1 100644 --- a/Doc/library/os.path.rst +++ b/Doc/library/os.path.rst @@ -308,8 +308,8 @@ the :mod:`glob` module.) Join one or more path segments intelligently. The return value is the concatenation of *path* and all members of *\*paths*, with exactly one - directory separator following each non-empty part except the last, meaning - that the result will end in a separator if the last part is empty. If + directory separator following each non-empty part except the last. That is, + if the last part is empty, the result will end in a separator. If a segment is an absolute path (which on Windows requires both a drive and a root), then all previous segments are ignored and joining continues from the absolute path segment.