From a978c6cb006f57024530f634f1600b8718aff5af Mon Sep 17 00:00:00 2001 From: Arthur Laureus Wigo <126365160+arthurlw@users.noreply.github.com> Date: Tue, 25 Feb 2025 14:39:15 -0800 Subject: [PATCH 1/3] Update os.path.rst --- Doc/library/os.path.rst | 42 ++++++++++++++++++++++++++++++----------- 1 file changed, 31 insertions(+), 11 deletions(-) diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst index ecbbc1d7605f9f..faa0d618d84ecb 100644 --- a/Doc/library/os.path.rst +++ b/Doc/library/os.path.rst @@ -55,11 +55,14 @@ the :mod:`glob` module.) .. function:: abspath(path) - Return a normalized absolutized version of the pathname *path*. On most platforms, this is equivalent to calling the function :func:`normpath` as follows: ``normpath(join(os.getcwd(), path))``. - + + .. seealso:: + :func:`join` - Used by abspath to combine paths + :func:`normpath` - Used by abspath to normalize paths + .. versionchanged:: 3.6 Accepts a :term:`path-like object`. @@ -238,14 +241,16 @@ the :mod:`glob` module.) .. function:: isabs(path) - Return ``True`` if *path* is an absolute pathname. On Unix, that means it begins with a slash, on Windows that it begins with two (back)slashes, or a drive letter, colon, and (back)slash together. - + + .. seealso:: + :func:`abspath` - Returns the absolute version of a path + .. versionchanged:: 3.6 Accepts a :term:`path-like object`. - + .. versionchanged:: 3.13 On Windows, returns ``False`` if the given path starts with exactly one (back)slash. @@ -351,7 +356,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 all members of *\*paths*, with exactly one directory separator following each non-empty part, except the last. That is, @@ -359,14 +364,24 @@ the :mod:`glob` module.) ends 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. - + + Examples:: + + >>> os.path.join('/home/foo', 'bar') + '/home/foo/bar' + >>> os.path.join('/home/foo', '/home/bar') + '/home/bar' + + The second example demonstrates how an absolute path argument ignores all + previous path segments. + On Windows, the drive is not reset when a rooted path segment (e.g., ``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 directory on drive :file:`C:` (:file:`c:foo`), not :file:`c:\\foo`. - + .. versionchanged:: 3.6 Accepts a :term:`path-like object` for *path* and *paths*. @@ -486,7 +501,7 @@ the :mod:`glob` module.) .. function:: split(path) - + Split the pathname *path* into a pair, ``(head, tail)`` where *tail* is the last pathname component and *head* is everything leading up to that. The *tail* part will never contain a slash; if *path* ends in a slash, *tail* @@ -496,9 +511,14 @@ the :mod:`glob` module.) all cases, ``join(head, tail)`` returns a path to the same location as *path* (but the strings may differ). Also see the functions :func:`dirname` and :func:`basename`. - + + .. seealso:: + :func:`join` - Can be used to reconstruct a path from split components + :func:`dirname` - Returns the directory name of a path + :func:`basename` - Returns the base name of a path + .. versionchanged:: 3.6 - Accepts a :term:`path-like object`. + Accepts a :term:`path-like object`.. .. function:: splitdrive(path) From 231335f751fe6da231229c832bad629834aeaab3 Mon Sep 17 00:00:00 2001 From: Arthur Laureus Wigo <126365160+arthurlw@users.noreply.github.com> Date: Tue, 25 Feb 2025 15:34:11 -0800 Subject: [PATCH 2/3] Adjusted os.path.rst details --- Doc/library/os.path.rst | 68 +++++++++++++++++++---------------------- 1 file changed, 32 insertions(+), 36 deletions(-) diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst index faa0d618d84ecb..285febe57b2619 100644 --- a/Doc/library/os.path.rst +++ b/Doc/library/os.path.rst @@ -55,14 +55,12 @@ the :mod:`glob` module.) .. function:: abspath(path) + Return a normalized absolutized version of the pathname *path*. On most - platforms, this is equivalent to calling the function :func:`normpath` as - follows: ``normpath(join(os.getcwd(), path))``. - - .. seealso:: - :func:`join` - Used by abspath to combine paths - :func:`normpath` - Used by abspath to normalize paths - + platforms, this is equivalent to calling ``normpath(join(os.getcwd(), path))``. + + .. seealso:: :func:`os.path.join` and :func:`os.path.normpath`. + .. versionchanged:: 3.6 Accepts a :term:`path-like object`. @@ -241,16 +239,15 @@ the :mod:`glob` module.) .. function:: isabs(path) + Return ``True`` if *path* is an absolute pathname. On Unix, that means it begins with a slash, on Windows that it begins with two (back)slashes, or a drive letter, colon, and (back)slash together. - - .. seealso:: - :func:`abspath` - Returns the absolute version of a path - + + .. seealso:: :func:`abspath` + .. versionchanged:: 3.6 Accepts a :term:`path-like object`. - .. versionchanged:: 3.13 On Windows, returns ``False`` if the given path starts with exactly one (back)slash. @@ -356,32 +353,36 @@ the :mod:`glob` module.) .. function:: join(path, *paths) - + 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. That is, the result will only end in a separator if the last part is either empty or - ends 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. - - Examples:: - + ends 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. For instance:: + >>> os.path.join('/home/foo', 'bar') '/home/foo/bar' >>> os.path.join('/home/foo', '/home/bar') '/home/bar' - - The second example demonstrates how an absolute path argument ignores all - previous path segments. - + On Windows, the drive is not reset when a rooted path segment (e.g., ``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, + absolute path, all previous segments are ignored and the drive is reset. For + instance:: + + >>> os.path.join('c:\\', 'foo') + 'c:\\foo' + >>> os.path.join('c:\\foo', 'd:\\bar') + 'd:\\bar' + + 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`. - + .. versionchanged:: 3.6 Accepts a :term:`path-like object` for *path* and *paths*. @@ -501,7 +502,7 @@ the :mod:`glob` module.) .. function:: split(path) - + Split the pathname *path* into a pair, ``(head, tail)`` where *tail* is the last pathname component and *head* is everything leading up to that. The *tail* part will never contain a slash; if *path* ends in a slash, *tail* @@ -509,16 +510,11 @@ the :mod:`glob` module.) *path* is empty, both *head* and *tail* are empty. Trailing slashes are stripped from *head* unless it is the root (one or more slashes only). In all cases, ``join(head, tail)`` returns a path to the same location as *path* - (but the strings may differ). Also see the functions :func:`dirname` and - :func:`basename`. - - .. seealso:: - :func:`join` - Can be used to reconstruct a path from split components - :func:`dirname` - Returns the directory name of a path - :func:`basename` - Returns the base name of a path - + (but the strings may differ). Also see the functions :func:`join`, + :func:`dirname` and :func:`basename`. + .. versionchanged:: 3.6 - Accepts a :term:`path-like object`.. + Accepts a :term:`path-like object`. .. function:: splitdrive(path) From 953a2e37f56340be713cf59542351bffa3a6d540 Mon Sep 17 00:00:00 2001 From: Arthur Laureus Wigo <126365160+arthurlw@users.noreply.github.com> Date: Thu, 27 Feb 2025 10:06:45 -0800 Subject: [PATCH 3/3] Update os.path.rst --- 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 285febe57b2619..94c33449979447 100644 --- a/Doc/library/os.path.rst +++ b/Doc/library/os.path.rst @@ -248,6 +248,7 @@ the :mod:`glob` module.) .. versionchanged:: 3.6 Accepts a :term:`path-like object`. + .. versionchanged:: 3.13 On Windows, returns ``False`` if the given path starts with exactly one (back)slash. @@ -362,7 +363,7 @@ the :mod:`glob` module.) 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. For instance:: + absolute path segment. For example:: >>> os.path.join('/home/foo', 'bar') '/home/foo/bar' @@ -372,7 +373,7 @@ the :mod:`glob` module.) On Windows, the drive is not reset when a rooted path segment (e.g., ``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. For - instance:: + example:: >>> os.path.join('c:\\', 'foo') 'c:\\foo'