Skip to content

Commit e5e1b94

Browse files
committed
pythongh-87691: clarify use of anchor and segment in pathlib docs
This is feedback from python#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.
1 parent cc87487 commit e5e1b94

File tree

1 file changed

+22
-22
lines changed

1 file changed

+22
-22
lines changed

Doc/library/pathlib.rst

Lines changed: 22 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -96,38 +96,38 @@ Pure path objects provide path-handling operations which don't actually
9696
access a filesystem. There are three ways to access these classes, which
9797
we also call *flavours*:
9898

99-
.. class:: PurePath(*pathsegments)
99+
.. class:: PurePath(*pathcomponents)
100100

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

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

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

111111
>>> PurePath('foo', 'some/path', 'bar')
112112
PurePosixPath('foo/some/path/bar')
113113
>>> PurePath(Path('foo'), Path('bar'))
114114
PurePosixPath('foo/bar')
115115

116-
When *pathsegments* is empty, the current directory is assumed::
116+
When *pathcomponents* is empty, the current directory is assumed::
117117

118118
>>> PurePath()
119119
PurePosixPath('.')
120120

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

124124
>>> PurePath('/etc', '/usr', 'lib64')
125125
PurePosixPath('/usr/lib64')
126126
>>> PureWindowsPath('c:/Windows', 'd:bar')
127127
PureWindowsPath('d:bar')
128128

129-
However, in a Windows path, changing the local root doesn't discard the
130-
previous drive setting::
129+
On Windows, the drive letter is not reset when a drive-less absolute path
130+
component (e.g., `r'\foo'`) is encountered::
131131

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

158-
.. class:: PurePosixPath(*pathsegments)
158+
.. class:: PurePosixPath(*pathcomponents)
159159

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

163163
>>> PurePosixPath('/etc')
164164
PurePosixPath('/etc')
165165

166-
*pathsegments* is specified similarly to :class:`PurePath`.
166+
*pathcomponents* is specified similarly to :class:`PurePath`.
167167

168-
.. class:: PureWindowsPath(*pathsegments)
168+
.. class:: PureWindowsPath(*pathcomponents)
169169

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

178-
*pathsegments* is specified similarly to :class:`PurePath`.
178+
*pathcomponents* is specified similarly to :class:`PurePath`.
179179

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

@@ -212,10 +212,10 @@ Paths of a different flavour compare unequal and cannot be ordered::
212212
Operators
213213
^^^^^^^^^
214214

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

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

692-
.. class:: Path(*pathsegments)
692+
.. class:: Path(*pathcomponents)
693693

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

701-
*pathsegments* is specified similarly to :class:`PurePath`.
701+
*pathcomponents* is specified similarly to :class:`PurePath`.
702702

703-
.. class:: PosixPath(*pathsegments)
703+
.. class:: PosixPath(*pathcomponents)
704704

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

708708
>>> PosixPath('/etc')
709709
PosixPath('/etc')
710710

711-
*pathsegments* is specified similarly to :class:`PurePath`.
711+
*pathcomponents* is specified similarly to :class:`PurePath`.
712712

713-
.. class:: WindowsPath(*pathsegments)
713+
.. class:: WindowsPath(*pathcomponents)
714714

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

718718
>>> WindowsPath('c:/Program Files/')
719719
WindowsPath('c:/Program Files')
720720

721-
*pathsegments* is specified similarly to :class:`PurePath`.
721+
*pathcomponents* is specified similarly to :class:`PurePath`.
722722

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

0 commit comments

Comments
 (0)