Skip to content

Commit 72aec4d

Browse files
StanFromIrelandStanFromIreland
committed
Split into lexical/IO
1 parent 67ded6a commit 72aec4d

File tree

1 file changed

+174
-156
lines changed

1 file changed

+174
-156
lines changed

‎Doc/library/os.path.rst‎

Lines changed: 174 additions & 156 deletions
Original file line numberDiff line numberDiff line change
@@ -54,24 +54,134 @@ the :mod:`glob` module.)
5454
unrepresentable at the OS level.
5555

5656

57-
.. function:: abspath(path)
57+
The module provides these functions for path manipulation:
5858

59-
Return a normalized absolutized version of the pathname *path*. On most
60-
platforms, this is equivalent to calling the function :func:`normpath` as
61-
follows: ``normpath(join(os.getcwd(), path))``.
59+
.. function:: join(path, *paths)
60+
61+
Join one or more path segments intelligently. The return value is the
62+
concatenation of *path* and all members of *\*paths*, with exactly one
63+
directory separator following each non-empty part, except the last. That is,
64+
the result will only end in a separator if the last part is either empty or
65+
ends in a separator. If a segment is an absolute path (which on Windows
66+
requires both a drive and a root), then all previous segments are ignored and
67+
joining continues from the absolute path segment.
68+
69+
On Windows, the drive is not reset when a rooted path segment (e.g.,
70+
``r'\foo'``) is encountered. If a segment is on a different drive or is an
71+
absolute path, all previous segments are ignored and the drive is reset. Note
72+
that since there is a current directory for each drive,
73+
``os.path.join("c:", "foo")`` represents a path relative to the current
74+
directory on drive :file:`C:` (:file:`c:foo`), not :file:`c:\\foo`.
75+
76+
.. versionchanged:: 3.6
77+
Accepts a :term:`path-like object` for *path* and *paths*.
78+
79+
80+
.. function:: normcase(path)
81+
82+
Normalize the case of a pathname. On Windows, convert all characters in the
83+
pathname to lowercase, and also convert forward slashes to backward slashes.
84+
On other operating systems, return the path unchanged.
6285

6386
.. versionchanged:: 3.6
6487
Accepts a :term:`path-like object`.
6588

6689

67-
.. function:: basename(path)
90+
.. function:: normpath(path)
6891

69-
Return the base name of pathname *path*. This is the second element of the
70-
pair returned by passing *path* to the function :func:`split`. Note that
71-
the result of this function is different
72-
from the Unix :program:`basename` program; where :program:`basename` for
73-
``'/foo/bar/'`` returns ``'bar'``, the :func:`basename` function returns an
74-
empty string (``''``).
92+
Normalize a pathname by collapsing redundant separators and up-level
93+
references so that ``A//B``, ``A/B/``, ``A/./B`` and ``A/foo/../B`` all
94+
become ``A/B``. This string manipulation may change the meaning of a path
95+
that contains symbolic links. On Windows, it converts forward slashes to
96+
backward slashes. To normalize case, use :func:`normcase`.
97+
98+
.. note::
99+
On POSIX systems, in accordance with `IEEE Std 1003.1 2013 Edition; 4.13
100+
Pathname Resolution <https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_13>`_,
101+
if a pathname begins with exactly two slashes, the first component
102+
following the leading characters may be interpreted in an implementation-defined
103+
manner, although more than two leading characters shall be treated as a
104+
single character.
105+
106+
.. versionchanged:: 3.6
107+
Accepts a :term:`path-like object`.
108+
109+
110+
.. function:: split(path)
111+
112+
Split the pathname *path* into a pair, ``(head, tail)`` where *tail* is the
113+
last pathname component and *head* is everything leading up to that. The
114+
*tail* part will never contain a slash; if *path* ends in a slash, *tail*
115+
will be empty. If there is no slash in *path*, *head* will be empty. If
116+
*path* is empty, both *head* and *tail* are empty. Trailing slashes are
117+
stripped from *head* unless it is the root (one or more slashes only). In
118+
all cases, ``join(head, tail)`` returns a path to the same location as *path*
119+
(but the strings may differ). Also see the functions :func:`dirname` and
120+
:func:`basename`.
121+
122+
.. versionchanged:: 3.6
123+
Accepts a :term:`path-like object`.
124+
125+
126+
.. function:: splitroot(path)
127+
128+
Split the pathname *path* into a 3-item tuple ``(drive, root, tail)`` where
129+
*drive* is a device name or mount point, *root* is a string of separators
130+
after the drive, and *tail* is everything after the root. Any of these
131+
items may be the empty string. In all cases, ``drive + root + tail`` will
132+
be the same as *path*.
133+
134+
On POSIX systems, *drive* is always empty. The *root* may be empty (if *path* is
135+
relative), a single forward slash (if *path* is absolute), or two forward slashes
136+
(implementation-defined per `IEEE Std 1003.1-2017; 4.13 Pathname Resolution
137+
<https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_13>`_.)
138+
For example::
139+
140+
>>> splitroot('/home/sam')
141+
('', '/', 'home/sam')
142+
>>> splitroot('//home/sam')
143+
('', '//', 'home/sam')
144+
>>> splitroot('///home/sam')
145+
('', '/', '//home/sam')
146+
147+
On Windows, *drive* may be empty, a drive-letter name, a UNC share, or a device
148+
name. The *root* may be empty, a forward slash, or a backward slash. For
149+
example::
150+
151+
>>> splitroot('C:/Users/Sam')
152+
('C:', '/', 'Users/Sam')
153+
>>> splitroot('//Server/Share/Users/Sam')
154+
('//Server/Share', '/', 'Users/Sam')
155+
156+
.. versionadded:: 3.12
157+
158+
159+
.. function:: splitext(path)
160+
161+
Split the pathname *path* into a pair ``(root, ext)`` such that ``root + ext ==
162+
path``, and the extension, *ext*, is empty or begins with a period and contains at
163+
most one period.
164+
165+
If the path contains no extension, *ext* will be ``''``::
166+
167+
>>> splitext('bar')
168+
('bar', '')
169+
170+
If the path contains an extension, then *ext* will be set to this extension,
171+
including the leading period. Note that previous periods will be ignored::
172+
173+
>>> splitext('foo.bar.exe')
174+
('foo.bar', '.exe')
175+
>>> splitext('/foo/bar.exe')
176+
('/foo/bar', '.exe')
177+
178+
Leading periods of the last component of the path are considered to
179+
be part of the root::
180+
181+
>>> splitext('.cshrc')
182+
('.cshrc', '')
183+
>>> splitext('/foo/....jpg')
184+
('/foo/....jpg', '')
75185

76186
.. versionchanged:: 3.6
77187
Accepts a :term:`path-like object`.
@@ -118,6 +228,19 @@ the :mod:`glob` module.)
118228
Accepts a :term:`path-like object`.
119229

120230

231+
.. function:: basename(path)
232+
233+
Return the base name of pathname *path*. This is the second element of the
234+
pair returned by passing *path* to the function :func:`split`. Note that
235+
the result of this function is different
236+
from the Unix :program:`basename` program; where :program:`basename` for
237+
``'/foo/bar/'`` returns ``'bar'``, the :func:`basename` function returns an
238+
empty string (``''``).
239+
240+
.. versionchanged:: 3.6
241+
Accepts a :term:`path-like object`.
242+
243+
121244
.. function:: dirname(path)
122245

123246
Return the directory name of pathname *path*. This is the first element of
@@ -127,6 +250,46 @@ the :mod:`glob` module.)
127250
Accepts a :term:`path-like object`.
128251

129252

253+
.. function:: isabs(path)
254+
255+
Return ``True`` if *path* is an absolute pathname. On Unix, that means it
256+
begins with a slash, on Windows that it begins with two (back)slashes, or a
257+
drive letter, colon, and (back)slash together.
258+
259+
.. versionchanged:: 3.6
260+
Accepts a :term:`path-like object`.
261+
262+
.. versionchanged:: 3.13
263+
On Windows, returns ``False`` if the given path starts with exactly one
264+
(back)slash.
265+
266+
267+
The module provides these I/O functions:
268+
269+
270+
.. function:: abspath(path)
271+
272+
Return a normalized absolutized version of the pathname *path*. On most
273+
platforms, this is equivalent to calling the function :func:`normpath` as
274+
follows: ``normpath(join(os.getcwd(), path))``.
275+
276+
.. versionchanged:: 3.6
277+
Accepts a :term:`path-like object`.
278+
279+
280+
.. function:: basename(path)
281+
282+
Return the base name of pathname *path*. This is the second element of the
283+
pair returned by passing *path* to the function :func:`split`. Note that
284+
the result of this function is different
285+
from the Unix :program:`basename` program; where :program:`basename` for
286+
``'/foo/bar/'`` returns ``'bar'``, the :func:`basename` function returns an
287+
empty string (``''``).
288+
289+
.. versionchanged:: 3.6
290+
Accepts a :term:`path-like object`.
291+
292+
130293
.. function:: exists(path)
131294

132295
Return ``True`` if *path* refers to an existing path or an open
@@ -237,20 +400,6 @@ the :mod:`glob` module.)
237400
Accepts a :term:`path-like object`.
238401

239402

240-
.. function:: isabs(path)
241-
242-
Return ``True`` if *path* is an absolute pathname. On Unix, that means it
243-
begins with a slash, on Windows that it begins with two (back)slashes, or a
244-
drive letter, colon, and (back)slash together.
245-
246-
.. versionchanged:: 3.6
247-
Accepts a :term:`path-like object`.
248-
249-
.. versionchanged:: 3.13
250-
On Windows, returns ``False`` if the given path starts with exactly one
251-
(back)slash.
252-
253-
254403
.. function:: isfile(path)
255404

256405
Return ``True`` if *path* is an :func:`existing <exists>` regular file.
@@ -350,57 +499,6 @@ the :mod:`glob` module.)
350499
.. versionadded:: 3.13
351500

352501

353-
.. function:: join(path, *paths)
354-
355-
Join one or more path segments intelligently. The return value is the
356-
concatenation of *path* and all members of *\*paths*, with exactly one
357-
directory separator following each non-empty part, except the last. That is,
358-
the result will only end in a separator if the last part is either empty or
359-
ends in a separator. If a segment is an absolute path (which on Windows
360-
requires both a drive and a root), then all previous segments are ignored and
361-
joining continues from the absolute path segment.
362-
363-
On Windows, the drive is not reset when a rooted path segment (e.g.,
364-
``r'\foo'``) is encountered. If a segment is on a different drive or is an
365-
absolute path, all previous segments are ignored and the drive is reset. Note
366-
that since there is a current directory for each drive,
367-
``os.path.join("c:", "foo")`` represents a path relative to the current
368-
directory on drive :file:`C:` (:file:`c:foo`), not :file:`c:\\foo`.
369-
370-
.. versionchanged:: 3.6
371-
Accepts a :term:`path-like object` for *path* and *paths*.
372-
373-
374-
.. function:: normcase(path)
375-
376-
Normalize the case of a pathname. On Windows, convert all characters in the
377-
pathname to lowercase, and also convert forward slashes to backward slashes.
378-
On other operating systems, return the path unchanged.
379-
380-
.. versionchanged:: 3.6
381-
Accepts a :term:`path-like object`.
382-
383-
384-
.. function:: normpath(path)
385-
386-
Normalize a pathname by collapsing redundant separators and up-level
387-
references so that ``A//B``, ``A/B/``, ``A/./B`` and ``A/foo/../B`` all
388-
become ``A/B``. This string manipulation may change the meaning of a path
389-
that contains symbolic links. On Windows, it converts forward slashes to
390-
backward slashes. To normalize case, use :func:`normcase`.
391-
392-
.. note::
393-
On POSIX systems, in accordance with `IEEE Std 1003.1 2013 Edition; 4.13
394-
Pathname Resolution <https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_13>`_,
395-
if a pathname begins with exactly two slashes, the first component
396-
following the leading characters may be interpreted in an implementation-defined
397-
manner, although more than two leading characters shall be treated as a
398-
single character.
399-
400-
.. versionchanged:: 3.6
401-
Accepts a :term:`path-like object`.
402-
403-
404502
.. function:: realpath(path, *, strict=False)
405503

406504
Return the canonical path of the specified filename, eliminating any symbolic
@@ -485,22 +583,6 @@ the :mod:`glob` module.)
485583
Accepts a :term:`path-like object`.
486584

487585

488-
.. function:: split(path)
489-
490-
Split the pathname *path* into a pair, ``(head, tail)`` where *tail* is the
491-
last pathname component and *head* is everything leading up to that. The
492-
*tail* part will never contain a slash; if *path* ends in a slash, *tail*
493-
will be empty. If there is no slash in *path*, *head* will be empty. If
494-
*path* is empty, both *head* and *tail* are empty. Trailing slashes are
495-
stripped from *head* unless it is the root (one or more slashes only). In
496-
all cases, ``join(head, tail)`` returns a path to the same location as *path*
497-
(but the strings may differ). Also see the functions :func:`dirname` and
498-
:func:`basename`.
499-
500-
.. versionchanged:: 3.6
501-
Accepts a :term:`path-like object`.
502-
503-
504586
.. function:: splitdrive(path)
505587

506588
Split the pathname *path* into a pair ``(drive, tail)`` where *drive* is either
@@ -526,70 +608,6 @@ the :mod:`glob` module.)
526608
Accepts a :term:`path-like object`.
527609

528610

529-
.. function:: splitroot(path)
530-
531-
Split the pathname *path* into a 3-item tuple ``(drive, root, tail)`` where
532-
*drive* is a device name or mount point, *root* is a string of separators
533-
after the drive, and *tail* is everything after the root. Any of these
534-
items may be the empty string. In all cases, ``drive + root + tail`` will
535-
be the same as *path*.
536-
537-
On POSIX systems, *drive* is always empty. The *root* may be empty (if *path* is
538-
relative), a single forward slash (if *path* is absolute), or two forward slashes
539-
(implementation-defined per `IEEE Std 1003.1-2017; 4.13 Pathname Resolution
540-
<https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_13>`_.)
541-
For example::
542-
543-
>>> splitroot('/home/sam')
544-
('', '/', 'home/sam')
545-
>>> splitroot('//home/sam')
546-
('', '//', 'home/sam')
547-
>>> splitroot('///home/sam')
548-
('', '/', '//home/sam')
549-
550-
On Windows, *drive* may be empty, a drive-letter name, a UNC share, or a device
551-
name. The *root* may be empty, a forward slash, or a backward slash. For
552-
example::
553-
554-
>>> splitroot('C:/Users/Sam')
555-
('C:', '/', 'Users/Sam')
556-
>>> splitroot('//Server/Share/Users/Sam')
557-
('//Server/Share', '/', 'Users/Sam')
558-
559-
.. versionadded:: 3.12
560-
561-
562-
.. function:: splitext(path)
563-
564-
Split the pathname *path* into a pair ``(root, ext)`` such that ``root + ext ==
565-
path``, and the extension, *ext*, is empty or begins with a period and contains at
566-
most one period.
567-
568-
If the path contains no extension, *ext* will be ``''``::
569-
570-
>>> splitext('bar')
571-
('bar', '')
572-
573-
If the path contains an extension, then *ext* will be set to this extension,
574-
including the leading period. Note that previous periods will be ignored::
575-
576-
>>> splitext('foo.bar.exe')
577-
('foo.bar', '.exe')
578-
>>> splitext('/foo/bar.exe')
579-
('/foo/bar', '.exe')
580-
581-
Leading periods of the last component of the path are considered to
582-
be part of the root::
583-
584-
>>> splitext('.cshrc')
585-
('.cshrc', '')
586-
>>> splitext('/foo/....jpg')
587-
('/foo/....jpg', '')
588-
589-
.. versionchanged:: 3.6
590-
Accepts a :term:`path-like object`.
591-
592-
593611
.. data:: supports_unicode_filenames
594612

595613
``True`` if arbitrary Unicode strings can be used as file names (within limitations

0 commit comments

Comments
 (0)