summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMiss Islington (bot) <31488909+miss-islington@users.noreply.github.com>2022-06-10 23:07:19 (GMT)
committerGitHub <noreply@github.com>2022-06-10 23:07:19 (GMT)
commit3a202de3bba88cea8f6f1425e69e66ca755b351c (patch)
treef5e66146c41fbcf9b4c2c8d8a200d7082556cde9
parentf9d0240db809fbb4443dc8f96a18e4c49af3fb7f (diff)
downloadcpython-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.rst33
-rw-r--r--Misc/NEWS.d/next/Documentation/2022-03-30-17-56-01.bpo-47161.gesHfS.rst2
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.