8000 gh-87691: clarify use of anchor in pathlib docs by hauntsaninja · Pull Request #100782 · python/cpython · GitHub
[go: up one dir, main page]
Skip to content

gh-87691: clarify use of anchor in pathlib docs #100782

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Jan 6, 2023
Merged

gh-87691: clarify use of anchor in pathlib docs #100782

Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
e5e1b94
gh-87691: clarify use of anchor and segment in pathlib docs
hauntsaninja Jan 5, 2023
ee8fc17
fix rst
hauntsaninja Jan 5, 2023
453cd76
use "drive", "ignored"
hauntsaninja Jan 6, 2023
9be6410
use segment
hauntsaninja Jan 6, 2023
9110498
revert segment
hauntsaninja Jan 6, 2023
ee484ba
Apply suggestions from code review
hauntsaninja Jan 6, 2023
05fe8dd
Update Doc/library/pathlib.rst
hauntsaninja Jan 6, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
gh-87691: clarify use of anchor and segment in pathlib docs 
This is feedback from #100737 (comment)

This matches the wording from the `os.path.join` docs better:
https://docs.python.org/3/library/os.path.html#os.path.join

In particular, the previous use of "anchor" was incorrect given the
pathlib definition of "anchor".

While matching wording, I noticed that the constructor section uses the
word "segment". This word does not appear elsewhere in the docs or code;
we already have "part" and "component" to refer to the same concept in the
pathlib context.
  • Loading branch information
@hauntsaninja
hauntsaninja committed Jan 5, 2023
commit e5e1b94571bc695afd8108ee48ee07dde01def49
44 changes: 22 additions & 22 deletions Doc/library/pathlib.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,38 +96,38 @@ Pure path objects provide path-handling operations which don't actually
access a filesystem. There are three ways to access these classes, which
we also call *flavours*:

.. class:: PurePath(*pathsegments)
.. class:: PurePath(*pathcomponents)

A generic class that represents the system's path flavour (instantiating
it creates either a :class:`PurePosixPath` or a :class:`PureWindowsPath`)::

>>> PurePath('setup.py') # Running on a Unix machine
PurePosixPath('setup.py')

Each element of *pathsegments* can be either a string representing a
path segment, an object implementing the :class:`os.PathLike` interface
Each element of *pathcomponents* can be either a string representing a
path component, an object implementing the :class:`os.PathLike` interface
which returns a string, or another path object::

>>> PurePath('foo', 'some/path', 'bar')
PurePosixPath('foo/some/path/bar')
>>> PurePath(Path('foo'), Path('bar'))
PurePosixPath('foo/bar')

When *pathsegments* is empty, the current directory is assumed::
When *pathcomponents* is empty, the current directory is assumed::

>>> PurePath()
PurePosixPath('.')

When several absolute paths are given, the last is taken as an anchor
(mimicking :func:`os.path.join`'s behaviour)::
If a component is an absolute path, all previous components are thrown away
(like :func:`os.path.join`')::

>>> PurePath('/etc', '/usr', 'lib64')
PurePosixPath('/usr/lib64')
>>> PureWindowsPath('c:/Windows', 'd:bar')
PureWindowsPath('d:bar')

However, in a Windows path, changing the local root doesn't discard the
previous drive setting::
On Windows, the drive letter is not reset when a drive-less absolute path
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the drive necessarily one letter?

Copy link
Contributor Author
@hauntsaninja hauntsaninja Jan 6, 2023 •
edited by AlexWaygood
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good question, I think the drive can be a UNC path. This also would need to get fixed in the os.path.join documentation: https://docs.python.org/3/library/os.path.html#os.path.join

>>> PureWindowsPath("hello", "//host/computer/dir", "/asdf")
PureWindowsPath('//host/computer/asdf')

>>> ntpath.join("hello", "//host/computer/dir", "/asdf")
'//host/computer/asdf'

I'll update to "drive" and open a second PR for os.path.join if @barneygale concurs

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"drive" makes more sense to me too.

component (e.g., `r'\foo'`) is encountered::

>>> PureWindowsPath('c:/Windows', '/Program Files')
PureWindowsPath('c:/Program Files')
Expand Down Expand Up @@ -155,17 +155,17 @@ we also call *flavours*:
.. versionchanged:: 3.6
Added support for the :class:`os.PathLike` interface.

.. class:: PurePosixPath(*pathsegments)
.. class:: PurePosixPath(*pathcomponents)

A subclass of :class:`PurePath`, this path flavour represents non-Windows
filesystem paths::

>>> PurePosixPath('/etc')
PurePosixPath('/etc')

*pathsegments* is specified similarly to :class:`PurePath`.
*pathcomponents* is specified similarly to :class: 10000 `PurePath`.

.. class:: PureWindowsPath(*pathsegments)
.. class:: PureWindowsPath(*pathcomponents)

A subclass of :class:`PurePath`, this path flavour represents Windows
filesystem paths, including `UNC paths`_::
Expand All @@ -175,7 +175,7 @@ we also call *flavours*:
>>> PureWindowsPath('//server/share/file')
PureWindowsPath('//server/share/file')

*pathsegments* is specified similarly to :class:`PurePath`.
*pathcomponents* is specified similarly to :class:`PurePath`.

.. _unc paths: https://en.wikipedia.org/wiki/Path_(computing)#UNC

Expand Down Expand Up @@ -212,10 +212,10 @@ Paths of a different flavour compare unequal and cannot be ordered::
Operators
^^^^^^^^^

The slash operator helps create child paths, mimicking the behaviour of
:func:`os.path.join`. For instance, when several absolute paths are given, the
last is taken as an anchor; for a Windows path, changing the local root doesn't
discard the previous drive setting::
The slash operator helps create child paths, like :func:`os.path.join`.
If the argument is an absolute path, the previous path components are thrown away.
On Windows, the drive letter is not reset when a drive-less absolute path
component (e.g., `r'\foo'`) is encountered::

>>> p = PurePath('/etc')
>>> p
Expand Down Expand Up @@ -689,7 +689,7 @@ Concrete paths are subclasses of the pure path classes. In addition to
operations provided by the latter, they also provide methods to do system
calls on path objects. There are three ways to instantiate concrete paths:

.. class:: Path(*pathsegments)
.. class:: Path(*pathcomponents)

A subclass of :class:`PurePath`, this class represents concrete paths of
the system's path flavour (instantiating it creates either a
Expand All @@ -698,27 +698,27 @@ calls on path objects. There are three ways to instantiate concrete paths:
>>> Path('setup.py')
PosixPath('setup.py')

*pathsegments* is specified similarly to :class:`PurePath`.
*pathcomponents* is specified similarly to :class:`PurePath`.

.. class:: PosixPath(*pathsegments)
.. class:: PosixPath(*pathcomponents)

A subclass of :class:`Path` and :class:`PurePosixPath`, this class
represents concrete non-Windows filesystem paths::

>>> PosixPath('/etc')
PosixPath('/etc')

*pathsegments* is specified similarly to :class:`PurePath`.
*pathcomponents* is specified similarly to :class:`PurePath`.

.. class:: WindowsPath(*pathsegments)
.. class:: WindowsPath(*pathcomponents)

A subclass of :class:`Path` and :class:`PureWindowsPath`, this class
represents concrete Windows filesystem paths::

>>> WindowsPath('c:/Program Files/')
WindowsPath('c:/Program Files')

*pathsegments* is specified similarly to :class:`PurePath`.
*pathcomponents* is specified similarly to :class:`PurePath`.

You can only instantiate the class flavour that corresponds to your system
(allowing system calls on non-compatible path flavours could lead to
Expand Down
0