[Python-checkins] gh-91317: Document that Path does not collapse initial `//` (GH-32193)

[miss-islington]

https://github.com/python/cpython/commit/9fafc0acf7a3bbd52d6867f15425783859cc3cbe
commit: 9fafc0acf7a3bbd52d6867f15425783859cc3cbe
branch: 3.10
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2022-06-10T16:10:29-07:00
summary:

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 at arhadthedev.net>

files:
A Misc/NEWS.d/next/Documentation/2022-03-30-17-56-01.bpo-47161.gesHfS.rst
M Doc/library/pathlib.rst

diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index 8077796ff6f6f..16a67bddc7076 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 0000000000000..6b552daa7c13a
--- /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.