https://github.com/python/cpython/commit/ba587ed8f33eb2a77fe6487e4cf6e254b9f81753
commit: ba587ed8f33eb2a77fe6487e4cf6e254b9f81753
branch: main
author: Arthur Wigo <[email protected]>
committer: hugovk <[email protected]>
date: 2025-12-16T13:29:52+02:00
summary:
gh-130536: Add details to `os.path` documentation (#130557)
files:
M Doc/library/os.path.rst
diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst
index c90e30ccf4fb8a..3cfe08a1fe1f7a 100644
--- a/Doc/library/os.path.rst
+++ b/Doc/library/os.path.rst
@@ -57,8 +57,9 @@ 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))``.
+ 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`.
@@ -243,6 +244,8 @@ the :mod:`glob` module.)
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`
+
.. versionchanged:: 3.6
Accepts a :term:`path-like object`.
@@ -357,14 +360,28 @@ the :mod:`glob` module.)
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.
+ 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. On Linux, for example::
+
+ >>> os.path.join('/home/foo', 'bar')
+ '/home/foo/bar'
+ >>> os.path.join('/home/foo', '/home/bar')
+ '/home/bar'
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
+ example::
+
+ >>> 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`.
@@ -527,8 +544,8 @@ 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`.
+ (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`.
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]
