From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Tue, 16 Dec 2025 14:50:58 +0000 (+0100)
Subject: [3.13] gh-130536: Add details to `os.path` documentation (GH-130557) (#142801)
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=bce4a201958b7e7575bc89335ca9eafa249df183;p=thirdparty%2FPython%2Fcpython.git

[3.13] gh-130536: Add details to `os.path` documentation (GH-130557) (#142801)

Co-authored-by: Arthur Wigo <arthur.l.wigo@gmail.com>
---

diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst
index e8a9de5cadb9..b07d346caf49 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`.
 
@@ -518,8 +535,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`.