Skip to content

Commit

Permalink
pythongh-91317: Document that Path does not collapse initial // (py…
Browse files Browse the repository at this point in the history
…thonGH-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 78f1a43)

Co-authored-by: Oleg Iarygin <oleg@arhadthedev.net>
  • Loading branch information
arhadthedev authored and miss-islington committed Jun 10, 2022
1 parent 8f36c73 commit fdf7cce
Show file tree
Hide file tree
Showing 2 changed files with 32 additions and 3 deletions.
33 changes: 30 additions & 3 deletions Doc/library/pathlib.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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')
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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::
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
Document that :class:`pathlib.PurePath` does not collapse
initial double slashes because they denote UNC paths.

0 comments on commit fdf7cce

Please sign in to comment.