mirror of https://github.com/python/cpython
gh-91317: Document that Path does not collapse initial `//` (GH-32193)
Documentation for `pathlib` says:
> Spurious slashes and single dots are collapsed, but double dots ('..') are not, since this would change the meaning of a path in the face of symbolic links:
However, it omits that initial double slashes also aren't collapsed.
Later, in documentation of `PurePath.drive`, `PurePath.root`, and `PurePath.name` it mentions UNC but:
- this abbreviation says nothing to a person who is unaware about existence of UNC (Wikipedia doesn't help either by [giving a disambiguation page](https://en.wikipedia.org/wiki/UNC))
- it shows up only if a person needs to use a specific property or decides to fully learn what the module provides.
For context, see the BPO entry.
(cherry picked from commit 78f1a43694
)
Co-authored-by: Oleg Iarygin <oleg@arhadthedev.net>
This commit is contained in:
parent
f9d0240db8
commit
3a202de3bb
|
@ -133,11 +133,13 @@ we also call *flavours*:
|
||||||
PureWindowsPath('c:/Program Files')
|
PureWindowsPath('c:/Program Files')
|
||||||
|
|
||||||
Spurious slashes and single dots are collapsed, but double dots (``'..'``)
|
Spurious slashes and single dots are collapsed, but double dots (``'..'``)
|
||||||
are not, since this would change the meaning of a path in the face of
|
and leading double slashes (``'//'``) are not, since this would change the
|
||||||
symbolic links::
|
meaning of a path for various reasons (e.g. symbolic links, UNC paths)::
|
||||||
|
|
||||||
>>> PurePath('foo//bar')
|
>>> PurePath('foo//bar')
|
||||||
PurePosixPath('foo/bar')
|
PurePosixPath('foo/bar')
|
||||||
|
>>> PurePath('//foo/bar')
|
||||||
|
PurePosixPath('//foo/bar')
|
||||||
>>> PurePath('foo/./bar')
|
>>> PurePath('foo/./bar')
|
||||||
PurePosixPath('foo/bar')
|
PurePosixPath('foo/bar')
|
||||||
>>> PurePath('foo/../bar')
|
>>> PurePath('foo/../bar')
|
||||||
|
@ -166,13 +168,17 @@ we also call *flavours*:
|
||||||
.. class:: PureWindowsPath(*pathsegments)
|
.. class:: PureWindowsPath(*pathsegments)
|
||||||
|
|
||||||
A subclass of :class:`PurePath`, this path flavour represents Windows
|
A subclass of :class:`PurePath`, this path flavour represents Windows
|
||||||
filesystem paths::
|
filesystem paths, including `UNC paths`_::
|
||||||
|
|
||||||
>>> PureWindowsPath('c:/Program Files/')
|
>>> PureWindowsPath('c:/Program Files/')
|
||||||
PureWindowsPath('c:/Program Files')
|
PureWindowsPath('c:/Program Files')
|
||||||
|
>>> PureWindowsPath('//server/share/file')
|
||||||
|
PureWindowsPath('//server/share/file')
|
||||||
|
|
||||||
*pathsegments* is specified similarly to :class:`PurePath`.
|
*pathsegments* is specified similarly to :class:`PurePath`.
|
||||||
|
|
||||||
|
.. _unc paths: https://en.wikipedia.org/wiki/Path_(computing)#UNC
|
||||||
|
|
||||||
Regardless of the system you're running on, you can instantiate all of
|
Regardless of the system you're running on, you can instantiate all of
|
||||||
these classes, since they don't provide any operation that does system calls.
|
these classes, since they don't provide any operation that does system calls.
|
||||||
|
|
||||||
|
@ -309,6 +315,27 @@ Pure paths provide the following methods and properties:
|
||||||
>>> PureWindowsPath('//host/share').root
|
>>> PureWindowsPath('//host/share').root
|
||||||
'\\'
|
'\\'
|
||||||
|
|
||||||
|
If the path starts with more than two successive slashes,
|
||||||
|
:class:`~pathlib.PurePosixPath` collapses them::
|
||||||
|
|
||||||
|
>>> PurePosixPath('//etc').root
|
||||||
|
'//'
|
||||||
|
>>> PurePosixPath('///etc').root
|
||||||
|
'/'
|
||||||
|
>>> PurePosixPath('////etc').root
|
||||||
|
'/'
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
This behavior conforms to *The Open Group Base Specifications Issue 6*,
|
||||||
|
paragraph `4.11 *Pathname Resolution* <xbd_path_resolution>`_:
|
||||||
|
|
||||||
|
*"A pathname that begins with two successive slashes may be interpreted in
|
||||||
|
an implementation-defined manner, although more than two leading slashes
|
||||||
|
shall be treated as a single slash."*
|
||||||
|
|
||||||
|
.. xbd_path_resolution: https://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap04.html#tag_04_11
|
||||||
|
|
||||||
.. data:: PurePath.anchor
|
.. data:: PurePath.anchor
|
||||||
|
|
||||||
The concatenation of the drive and root::
|
The concatenation of the drive and root::
|
||||||
|
|
|
@ -0,0 +1,2 @@
|
||||||
|
Document that :class:`pathlib.PurePath` does not collapse
|
||||||
|
initial double slashes because they denote UNC paths.
|
Loading…
Reference in New Issue