From fb499371afac8fccd4db1a17bc9b8fe6c47bc826 Mon Sep 17 00:00:00 2001 From: Oleg Iarygin Date: Wed, 30 Mar 2022 17:21:38 +0300 Subject: [PATCH 1/9] Document that Path does not collapse initial `//` --- Doc/library/pathlib.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 1e7bc315471e2c..1982139336be29 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -133,11 +133,14 @@ 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 initial double slashes (``'//'``) are not, since this would change the + meaning of a path in the face of symbolic links and UNC (network) paths + respectively:: >>> PurePath('foo//bar') PurePosixPath('foo/bar') + >>> PurePath('//foo/bar') + PurePosixPath('//foo/bar') >>> PurePath('foo/./bar') PurePosixPath('foo/bar') >>> PurePath('foo/../bar') From 0cf996b02733fb67259db9af491c80d4643cc32b Mon Sep 17 00:00:00 2001 From: Oleg Iarygin Date: Wed, 30 Mar 2022 17:56:39 +0300 Subject: [PATCH 2/9] Add a NEWS entry --- .../next/Documentation/2022-03-30-17-56-01.bpo-47161.gesHfS.rst | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 Misc/NEWS.d/next/Documentation/2022-03-30-17-56-01.bpo-47161.gesHfS.rst 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..eb42ca8dfd1b8c --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2022-03-30-17-56-01.bpo-47161.gesHfS.rst @@ -0,0 +1,2 @@ +Explicitly documented that :class:`pathlib.PurePath` does not collapse +initial double slashes because they denote UNC paths. Patch by Oleg Iarygin. From ad0de0123a964882ea4122d34c9a27a9ac848c37 Mon Sep 17 00:00:00 2001 From: Oleg Iarygin Date: Thu, 31 Mar 2022 06:24:10 +0300 Subject: [PATCH 3/9] Update Misc/NEWS.d/next/Documentation/2022-03-30-17-56-01.bpo-47161.gesHfS.rst Co-authored-by: Jelle Zijlstra --- .../next/Documentation/2022-03-30-17-56-01.bpo-47161.gesHfS.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index eb42ca8dfd1b8c..9fb66d52a7bd34 100644 --- 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 @@ -1,2 +1,2 @@ -Explicitly documented that :class:`pathlib.PurePath` does not collapse +Document that :class:`pathlib.PurePath` does not collapse initial double slashes because they denote UNC paths. Patch by Oleg Iarygin. From ab2f28541e7dcc05be478470452c1d7d97e03779 Mon Sep 17 00:00:00 2001 From: Oleg Iarygin Date: Wed, 8 Jun 2022 15:09:50 +0300 Subject: [PATCH 4/9] Address the review of Bratt Cannon Co-authored-by: Brett Cannon --- Doc/library/pathlib.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index d6e19770d81bd2..5b585e45c94ce5 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -133,9 +133,8 @@ we also call *flavours*: PureWindowsPath('c:/Program Files') Spurious slashes and single dots are collapsed, but double dots (``'..'``) - and initial double slashes (``'//'``) are not, since this would change the - meaning of a path in the face of symbolic links and UNC (network) paths - respectively:: + 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') From 31dc415136c4c4d9d3a2c46b64d0a1c48cece60a Mon Sep 17 00:00:00 2001 From: Oleg Iarygin Date: Wed, 8 Jun 2022 18:32:02 +0300 Subject: [PATCH 5/9] Address the review of Barney Gale Co-authored-by: Barney Gale --- Doc/library/pathlib.rst | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 5b585e45c94ce5..12466a29fbed00 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -168,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. @@ -311,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:: From 207b2d6bf98ff55a14350ac2796e89d3469905b2 Mon Sep 17 00:00:00 2001 From: Oleg Iarygin Date: Wed, 8 Jun 2022 19:05:27 +0300 Subject: [PATCH 6/9] Do not use spaces inside links --- Doc/library/pathlib.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 12466a29fbed00..3796e5ab819181 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -168,7 +168,7 @@ we also call *flavours*: .. class:: PureWindowsPath(*pathsegments) A subclass of :class:`PurePath`, this path flavour represents Windows - filesystem paths, including `UNC paths`_:: + filesystem paths, including `UNC`_ paths:: >>> PureWindowsPath('c:/Program Files/') PureWindowsPath('c:/Program Files') @@ -177,7 +177,7 @@ we also call *flavours*: *pathsegments* is specified similarly to :class:`PurePath`. - .. UNC paths: https://en.wikipedia.org/wiki/Path_(computing)#UNC + .. UNC: 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. From 519078a90118046956f4ae54a0c7908c7fafbc51 Mon Sep 17 00:00:00 2001 From: Oleg Iarygin Date: Wed, 8 Jun 2022 19:18:17 +0300 Subject: [PATCH 7/9] Address "Unknown target name: unc" --- Doc/library/pathlib.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 3796e5ab819181..028ea39b08094f 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -168,7 +168,7 @@ we also call *flavours*: .. class:: PureWindowsPath(*pathsegments) A subclass of :class:`PurePath`, this path flavour represents Windows - filesystem paths, including `UNC`_ paths:: + filesystem paths, including `UNC paths`_:: >>> PureWindowsPath('c:/Program Files/') PureWindowsPath('c:/Program Files') @@ -177,7 +177,7 @@ we also call *flavours*: *pathsegments* is specified similarly to :class:`PurePath`. - .. UNC: https://en.wikipedia.org/wiki/Path_(computing)#UNC + .. 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. From a307bd319d9e72299eeb262cce7b93085befcf98 Mon Sep 17 00:00:00 2001 From: Oleg Iarygin Date: Wed, 8 Jun 2022 19:30:02 +0300 Subject: [PATCH 8/9] Fix the link --- Doc/library/pathlib.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 028ea39b08094f..982b567785168d 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -177,7 +177,7 @@ we also call *flavours*: *pathsegments* is specified similarly to :class:`PurePath`. - .. unc paths: https://en.wikipedia.org/wiki/Path_(computing)#UNC + .. _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. From 6d76a314cd4b67e470aa946035694e6c185d4690 Mon Sep 17 00:00:00 2001 From: Oleg Iarygin Date: Wed, 8 Jun 2022 22:16:46 +0300 Subject: [PATCH 9/9] Remove my provenance from NEWS because it's a community effort now. --- .../next/Documentation/2022-03-30-17-56-01.bpo-47161.gesHfS.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 9fb66d52a7bd34..6b552daa7c13af 100644 --- 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 @@ -1,2 +1,2 @@ Document that :class:`pathlib.PurePath` does not collapse -initial double slashes because they denote UNC paths. Patch by Oleg Iarygin. +initial double slashes because they denote UNC paths.