diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 8077796ff6f6fd..16a67bddc7076e 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* `_: + + *"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 00000000000000..6b552daa7c13af --- /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. pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.

Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy