diff options
author | Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com> | 2022-06-10 23:07:19 (GMT) |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-06-10 23:07:19 (GMT) |
commit | 3a202de3bba88cea8f6f1425e69e66ca755b351c (patch) | |
tree | f5e66146c41fbcf9b4c2c8d8a200d7082556cde9 | |
parent | f9d0240db809fbb4443dc8f96a18e4c49af3fb7f (diff) | |
download | cpython-3a202de3bba88cea8f6f1425e69e66ca755b351c.zip cpython-3a202de3bba88cea8f6f1425e69e66ca755b351c.tar.gz cpython-3a202de3bba88cea8f6f1425e69e66ca755b351c.tar.bz2 |
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 78f1a436949209dab1f4a9d04036a1a42b165086)
Co-authored-by: Oleg Iarygin <oleg@arhadthedev.net>
-rw-r--r-- | Doc/library/pathlib.rst | 33 | ||||
-rw-r--r-- | Misc/NEWS.d/next/Documentation/2022-03-30-17-56-01.bpo-47161.gesHfS.rst | 2 |
2 files changed, 32 insertions, 3 deletions
diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 5720334..29b0c2f 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -133,11 +133,13 @@ we also call *flavours*: PureWindowsPath('c:/Program Files') 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:: + and leading double slashes (``'//'``) are not, since this would change the + meaning of a path for various reasons (e.g. symbolic links, UNC paths):: >>> PurePath('foo//bar') PurePosixPath('foo/bar') + >>> PurePath('//foo/bar') + PurePosixPath('//foo/bar') >>> PurePath('foo/./bar') PurePosixPath('foo/bar') >>> PurePath('foo/../bar') @@ -166,13 +168,17 @@ we also call *flavours*: .. class:: PureWindowsPath(*pathsegments) 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('//server/share/file') + PureWindowsPath('//server/share/file') *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 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 '\\' + 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 The concatenation of the drive and root:: diff --git a/Misc/NEWS.d/next/Documentation/2022-03-30-17-56-01.bpo-47161.gesHfS.rst b/Misc/NEWS.d/next/Documentation/2022-03-30-17-56-01.bpo-47161.gesHfS.rst new file mode 100644 index 0000000..6b552da --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2022-03-30-17-56-01.bpo-47161.gesHfS.rst @@ -0,0 +1,2 @@ +Document that :class:`pathlib.PurePath` does not collapse +initial double slashes because they denote UNC paths. |