From 421bf4eb71e849b21e44a2b91735b0991f3fd837 Mon Sep 17 00:00:00 2001 From: Shamil Date: Tue, 27 May 2025 00:59:36 +0300 Subject: [PATCH] gh-134639: Clarify what "canonical" means in os.path.realpath Improve documentation for os.path.realpath by clearly defining what a "canonical path" means. The updated documentation now explicitly states that a canonical path: - Is an absolute path - Has all symbolic links resolved - Is normalized (redundant separators, '.' and '..' components removed) Also clarify platform-specific behavior: - On Windows: resolves MS-DOS (8.3) style names and junction points - On POSIX: roughly equivalent to the system's realpath() function Closes #134639 --- Doc/library/os.path.rst | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst index ecbbc1d7605f9f..cb6287990dd2e2 100644 --- a/Doc/library/os.path.rst +++ b/Doc/library/os.path.rst @@ -403,10 +403,18 @@ the :mod:`glob` module.) .. function:: realpath(path, *, strict=False) - Return the canonical path of the specified filename, eliminating any symbolic - 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``. + Return the canonical path of the specified filename. A canonical path: + + * Is an absolute path (always starts from the root of the filesystem) + * Has all symbolic links resolved (if supported by the operating system) + * Is normalized (redundant separators, ``.`` and ``..`` components are removed) + + On Windows, this function will also resolve MS-DOS (also called 8.3) + style names such as ``C:\\PROGRA~1`` to ``C:\\Program Files`` and + will resolve junction points. + + On POSIX systems, this function is roughly equivalent to the system's + ``realpath()`` function. If a path doesn't exist or a symlink loop is encountered, and *strict* is ``True``, :exc:`OSError` is raised. If *strict* is ``False`` these errors