From 55d3e8aa02b70b763dbefa2cd645be9fbfcd638e Mon Sep 17 00:00:00 2001
From: Serhiy Storchaka <storchaka@gmail.com>
Date: Sat, 8 Aug 2026 19:33:37 +0300
Subject: [PATCH] gh-84548: Document Windows specific behavior of abspath() and
 realpath()

On Windows abspath() resolves a drive-relative path against the current
directory of the specified drive, capitalizes the drive letter and strips
trailing dots and spaces, so the result can differ from
normpath(join(os.getcwd(), path)).  realpath() returns the path in the case
reported by the operating system.
---
 Doc/library/os.path.rst | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst
index 808187061733be0..f5ddb426c915f5a 100644
--- a/Doc/library/os.path.rst
+++ b/Doc/library/os.path.rst
@@ -59,6 +59,18 @@ the :mod:`glob` module.)
    Return a normalized absolutized version of the pathname *path*. On most
    platforms, this is equivalent to calling ``normpath(join(os.getcwd(), path))``.
 
+   On Windows the path is normalized by the operating system,
+   therefore the result can differ from ``normpath(join(os.getcwd(), path))``.
+   A drive-relative path is resolved against the current directory
+   of the specified drive, and the drive letter is capitalized.
+   Trailing dots and spaces are stripped.
+   For example::
+
+      >>> os.path.abspath('c:spam')
+      'C:\\Temp\\spam'
+      >>> os.path.abspath('c:/temp/spam. . .')
+      'c:\\temp\\spam'
+
    .. seealso:: :func:`os.path.join` and :func:`os.path.normpath`.
 
    .. versionchanged:: 3.6
@@ -435,6 +447,9 @@ the :mod:`glob` module.)
    links encountered in the path (if they are supported by the operating
    system). On Windows, this function will also resolve MS-DOS (also called 8.3)
    style names such as ``C:\\PROGRA~1`` to ``C:\\Program Files``.
+   The returned path uses the case reported by the operating system,
+   which can differ from the case of *path*,
+   in particular the drive letter is capitalized.
 
    By default, the path is evaluated up to the first component that does not
    exist, is a symlink loop, or whose evaluation raises :exc:`OSError`.