From 72aec4d34e529d5d888429c683a58d190ea91c86 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Fri, 11 Apr 2025 16:51:49 +0100 Subject: [PATCH 1/2] Split into lexical/IO --- Doc/library/os.path.rst | 330 +++++++++++++++++++++------------------- 1 file changed, 174 insertions(+), 156 deletions(-) diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst index ecbbc1d7605f9f..2473e997e27b5a 100644 --- a/Doc/library/os.path.rst +++ b/Doc/library/os.path.rst @@ -54,24 +54,134 @@ the :mod:`glob` module.) unrepresentable at the OS level. -.. function:: abspath(path) +The module provides these functions for path manipulation: - 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))``. +.. 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. + + 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*. + + +.. function:: normcase(path) + + Normalize the case of a pathname. On Windows, convert all characters in the + pathname to lowercase, and also convert forward slashes to backward slashes. + On other operating systems, return the path unchanged. .. versionchanged:: 3.6 Accepts a :term:`path-like object`. -.. function:: basename(path) +.. function:: normpath(path) - Return the base name of pathname *path*. This is the second element of the - pair returned by passing *path* to the function :func:`split`. Note that - the result of this function is different - from the Unix :program:`basename` program; where :program:`basename` for - ``'/foo/bar/'`` returns ``'bar'``, the :func:`basename` function returns an - empty string (``''``). + Normalize a pathname by collapsing redundant separators and up-level + references so that ``A//B``, ``A/B/``, ``A/./B`` and ``A/foo/../B`` all + become ``A/B``. This string manipulation may change the meaning of a path + that contains symbolic links. On Windows, it converts forward slashes to + backward slashes. To normalize case, use :func:`normcase`. + + .. note:: + On POSIX systems, in accordance with `IEEE Std 1003.1 2013 Edition; 4.13 + Pathname Resolution `_, + if a pathname begins with exactly two slashes, the first component + following the leading characters may be interpreted in an implementation-defined + manner, although more than two leading characters shall be treated as a + single character. + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + + +.. 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* + will be empty. If there is no slash in *path*, *head* will be empty. If + *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`. + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + + +.. function:: splitroot(path) + + Split the pathname *path* into a 3-item tuple ``(drive, root, tail)`` where + *drive* is a device name or mount point, *root* is a string of separators + after the drive, and *tail* is everything after the root. Any of these + items may be the empty string. In all cases, ``drive + root + tail`` will + be the same as *path*. + + On POSIX systems, *drive* is always empty. The *root* may be empty (if *path* is + relative), a single forward slash (if *path* is absolute), or two forward slashes + (implementation-defined per `IEEE Std 1003.1-2017; 4.13 Pathname Resolution + `_.) + For example:: + + >>> splitroot('/home/sam') + ('', '/', 'home/sam') + >>> splitroot('//home/sam') + ('', '//', 'home/sam') + >>> splitroot('///home/sam') + ('', '/', '//home/sam') + + On Windows, *drive* may be empty, a drive-letter name, a UNC share, or a device + name. The *root* may be empty, a forward slash, or a backward slash. For + example:: + + >>> splitroot('C:/Users/Sam') + ('C:', '/', 'Users/Sam') + >>> splitroot('//Server/Share/Users/Sam') + ('//Server/Share', '/', 'Users/Sam') + + .. versionadded:: 3.12 + + +.. function:: splitext(path) + + Split the pathname *path* into a pair ``(root, ext)`` such that ``root + ext == + path``, and the extension, *ext*, is empty or begins with a period and contains at + most one period. + + If the path contains no extension, *ext* will be ``''``:: + + >>> splitext('bar') + ('bar', '') + + If the path contains an extension, then *ext* will be set to this extension, + including the leading period. Note that previous periods will be ignored:: + + >>> splitext('foo.bar.exe') + ('foo.bar', '.exe') + >>> splitext('/foo/bar.exe') + ('/foo/bar', '.exe') + + Leading periods of the last component of the path are considered to + be part of the root:: + + >>> splitext('.cshrc') + ('.cshrc', '') + >>> splitext('/foo/....jpg') + ('/foo/....jpg', '') .. versionchanged:: 3.6 Accepts a :term:`path-like object`. @@ -118,6 +228,19 @@ the :mod:`glob` module.) Accepts a :term:`path-like object`. +.. function:: basename(path) + + Return the base name of pathname *path*. This is the second element of the + pair returned by passing *path* to the function :func:`split`. Note that + the result of this function is different + from the Unix :program:`basename` program; where :program:`basename` for + ``'/foo/bar/'`` returns ``'bar'``, the :func:`basename` function returns an + empty string (``''``). + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + + .. function:: dirname(path) Return the directory name of pathname *path*. This is the first element of @@ -127,6 +250,46 @@ the :mod:`glob` module.) Accepts a :term:`path-like object`. +.. 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. + + .. 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. + + +The module provides these I/O functions: + + +.. 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))``. + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + + +.. function:: basename(path) + + Return the base name of pathname *path*. This is the second element of the + pair returned by passing *path* to the function :func:`split`. Note that + the result of this function is different + from the Unix :program:`basename` program; where :program:`basename` for + ``'/foo/bar/'`` returns ``'bar'``, the :func:`basename` function returns an + empty string (``''``). + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + + .. function:: exists(path) Return ``True`` if *path* refers to an existing path or an open @@ -237,20 +400,6 @@ the :mod:`glob` module.) Accepts a :term:`path-like object`. -.. 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. - - .. 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. - - .. function:: isfile(path) Return ``True`` if *path* is an :func:`existing ` regular file. @@ -350,57 +499,6 @@ the :mod:`glob` module.) .. versionadded:: 3.13 -.. 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. - - 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*. - - -.. function:: normcase(path) - - Normalize the case of a pathname. On Windows, convert all characters in the - pathname to lowercase, and also convert forward slashes to backward slashes. - On other operating systems, return the path unchanged. - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object`. - - -.. function:: normpath(path) - - Normalize a pathname by collapsing redundant separators and up-level - references so that ``A//B``, ``A/B/``, ``A/./B`` and ``A/foo/../B`` all - become ``A/B``. This string manipulation may change the meaning of a path - that contains symbolic links. On Windows, it converts forward slashes to - backward slashes. To normalize case, use :func:`normcase`. - - .. note:: - On POSIX systems, in accordance with `IEEE Std 1003.1 2013 Edition; 4.13 - Pathname Resolution `_, - if a pathname begins with exactly two slashes, the first component - following the leading characters may be interpreted in an implementation-defined - manner, although more than two leading characters shall be treated as a - single character. - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object`. - - .. function:: realpath(path, *, strict=False) Return the canonical path of the specified filename, eliminating any symbolic @@ -485,22 +583,6 @@ the :mod:`glob` module.) Accepts a :term:`path-like object`. -.. 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* - will be empty. If there is no slash in *path*, *head* will be empty. If - *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`. - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object`. - - .. function:: splitdrive(path) Split the pathname *path* into a pair ``(drive, tail)`` where *drive* is either @@ -526,70 +608,6 @@ the :mod:`glob` module.) Accepts a :term:`path-like object`. -.. function:: splitroot(path) - - Split the pathname *path* into a 3-item tuple ``(drive, root, tail)`` where - *drive* is a device name or mount point, *root* is a string of separators - after the drive, and *tail* is everything after the root. Any of these - items may be the empty string. In all cases, ``drive + root + tail`` will - be the same as *path*. - - On POSIX systems, *drive* is always empty. The *root* may be empty (if *path* is - relative), a single forward slash (if *path* is absolute), or two forward slashes - (implementation-defined per `IEEE Std 1003.1-2017; 4.13 Pathname Resolution - `_.) - For example:: - - >>> splitroot('/home/sam') - ('', '/', 'home/sam') - >>> splitroot('//home/sam') - ('', '//', 'home/sam') - >>> splitroot('///home/sam') - ('', '/', '//home/sam') - - On Windows, *drive* may be empty, a drive-letter name, a UNC share, or a device - name. The *root* may be empty, a forward slash, or a backward slash. For - example:: - - >>> splitroot('C:/Users/Sam') - ('C:', '/', 'Users/Sam') - >>> splitroot('//Server/Share/Users/Sam') - ('//Server/Share', '/', 'Users/Sam') - - .. versionadded:: 3.12 - - -.. function:: splitext(path) - - Split the pathname *path* into a pair ``(root, ext)`` such that ``root + ext == - path``, and the extension, *ext*, is empty or begins with a period and contains at - most one period. - - If the path contains no extension, *ext* will be ``''``:: - - >>> splitext('bar') - ('bar', '') - - If the path contains an extension, then *ext* will be set to this extension, - including the leading period. Note that previous periods will be ignored:: - - >>> splitext('foo.bar.exe') - ('foo.bar', '.exe') - >>> splitext('/foo/bar.exe') - ('/foo/bar', '.exe') - - Leading periods of the last component of the path are considered to - be part of the root:: - - >>> splitext('.cshrc') - ('.cshrc', '') - >>> splitext('/foo/....jpg') - ('/foo/....jpg', '') - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object`. - - .. data:: supports_unicode_filenames ``True`` if arbitrary Unicode strings can be used as file names (within limitations From 595258510c647e8b5afef22d577719ba6b94cd0f Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Fri, 11 Apr 2025 16:54:25 +0100 Subject: [PATCH 2/2] fixup! Split into lexical/IO --- Doc/library/os.path.rst | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst index 2473e997e27b5a..0cbe4dd9e966b2 100644 --- a/Doc/library/os.path.rst +++ b/Doc/library/os.path.rst @@ -277,19 +277,6 @@ The module provides these I/O functions: Accepts a :term:`path-like object`. -.. function:: basename(path) - - Return the base name of pathname *path*. This is the second element of the - pair returned by passing *path* to the function :func:`split`. Note that - the result of this function is different - from the Unix :program:`basename` program; where :program:`basename` for - ``'/foo/bar/'`` returns ``'bar'``, the :func:`basename` function returns an - empty string (``''``). - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object`. - - .. function:: exists(path) Return ``True`` if *path* refers to an existing path or an open