From e5e1b94571bc695afd8108ee48ee07dde01def49 Mon Sep 17 00:00:00 2001 From: hauntsaninja Date: Thu, 5 Jan 2023 15:47:19 -0800 Subject: [PATCH 1/7] gh-87691: clarify use of anchor and segment in pathlib docs This is feedback from https://github.com/python/cpython/pull/100737#discussion_r1062968696 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. --- Doc/library/pathlib.rst | 44 ++++++++++++++++++++--------------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index c90758c9306c72..fad8bed66b390f 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -96,7 +96,7 @@ 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`):: @@ -104,8 +104,8 @@ we also call *flavours*: >>> 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') @@ -113,21 +113,21 @@ we also call *flavours*: >>> 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 + component (e.g., `r'\foo'`) is encountered:: >>> PureWindowsPath('c:/Windows', '/Program Files') PureWindowsPath('c:/Program Files') @@ -155,7 +155,7 @@ 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:: @@ -163,9 +163,9 @@ we also call *flavours*: >>> PurePosixPath('/etc') PurePosixPath('/etc') - *pathsegments* is specified similarly to :class:`PurePath`. + *pathcomponents* is specified similarly to :class:`PurePath`. -.. class:: PureWindowsPath(*pathsegments) +.. class:: PureWindowsPath(*pathcomponents) A subclass of :class:`PurePath`, this path flavour represents Windows filesystem paths, including `UNC paths`_:: @@ -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 @@ -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 @@ -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 @@ -698,9 +698,9 @@ 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:: @@ -708,9 +708,9 @@ calls on path objects. There are three ways to instantiate concrete 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:: @@ -718,7 +718,7 @@ calls on path objects. There are three ways to instantiate concrete 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 From ee8fc17714fac2410785abe51fb4eb5f41064a5b Mon Sep 17 00:00:00 2001 From: hauntsaninja Date: Thu, 5 Jan 2023 15:55:52 -0800 Subject: [PATCH 2/7] fix rst --- 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 fad8bed66b390f..4842255f44dd39 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -127,7 +127,7 @@ we also call *flavours*: PureWindowsPath('d:bar') On Windows, the drive letter is not reset when a drive-less absolute path - component (e.g., `r'\foo'`) is encountered:: + component (e.g., ``r'\foo'``) is encountered:: >>> PureWindowsPath('c:/Windows', '/Program Files') PureWindowsPath('c:/Program Files') @@ -215,7 +215,7 @@ Operators 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:: +component (e.g., ``r'\foo'``) is encountered:: >>> p = PurePath('/etc') >>> p From 453cd765a6ef0a23fbb54d1514e7afbd3b1e0cb8 Mon Sep 17 00:00:00 2001 From: hauntsaninja Date: Thu, 5 Jan 2023 16:44:07 -0800 Subject: [PATCH 3/7] use "drive", "ignored" --- Doc/library/pathlib.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 4842255f44dd39..6c563675f004c8 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -118,7 +118,7 @@ we also call *flavours*: >>> PurePath() PurePosixPath('.') - If a component is an absolute path, all previous components are thrown away + If a component is an absolute path, all previous components are ignored (like :func:`os.path.join`'):: >>> PurePath('/etc', '/usr', 'lib64') @@ -126,7 +126,7 @@ we also call *flavours*: >>> PureWindowsPath('c:/Windows', 'd:bar') PureWindowsPath('d:bar') - On Windows, the drive letter is not reset when a drive-less absolute path + On Windows, the drive is not reset when a drive-less absolute path component (e.g., ``r'\foo'``) is encountered:: >>> PureWindowsPath('c:/Windows', '/Program Files') @@ -213,8 +213,8 @@ Operators ^^^^^^^^^ 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 +If the argument is an absolute path, the previous path components are ignored. +On Windows, the drive is not reset when a drive-less absolute path component (e.g., ``r'\foo'``) is encountered:: >>> p = PurePath('/etc') From 9be64100576f8dae7f674919c5445ddb6e23050f Mon Sep 17 00:00:00 2001 From: hauntsaninja Date: Thu, 5 Jan 2023 16:46:00 -0800 Subject: [PATCH 4/7] use segment --- Doc/library/pathlib.rst | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 6c563675f004c8..235deaaef50e0a 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -96,7 +96,7 @@ 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(*pathcomponents) +.. class:: PurePath(*pathsegments) A generic class that represents the system's path flavour (instantiating it creates either a :class:`PurePosixPath` or a :class:`PureWindowsPath`):: @@ -104,8 +104,8 @@ we also call *flavours*: >>> PurePath('setup.py') # Running on a Unix machine PurePosixPath('setup.py') - Each element of *pathcomponents* can be either a string representing a - path component, an object implementing the :class:`os.PathLike` interface + Each element of *pathsegments* can be either a string representing a + path segment, an object implementing the :class:`os.PathLike` interface which returns a string, or another path object:: >>> PurePath('foo', 'some/path', 'bar') @@ -113,7 +113,7 @@ we also call *flavours*: >>> PurePath(Path('foo'), Path('bar')) PurePosixPath('foo/bar') - When *pathcomponents* is empty, the current directory is assumed:: + When *pathsegments* is empty, the current directory is assumed:: >>> PurePath() PurePosixPath('.') @@ -155,7 +155,7 @@ we also call *flavours*: .. versionchanged:: 3.6 Added support for the :class:`os.PathLike` interface. -.. class:: PurePosixPath(*pathcomponents) +.. class:: PurePosixPath(*pathsegments) A subclass of :class:`PurePath`, this path flavour represents non-Windows filesystem paths:: @@ -163,9 +163,9 @@ we also call *flavours*: >>> PurePosixPath('/etc') PurePosixPath('/etc') - *pathcomponents* is specified similarly to :class:`PurePath`. + *pathsegments* is specified similarly to :class:`PurePath`. -.. class:: PureWindowsPath(*pathcomponents) +.. class:: PureWindowsPath(*pathsegments) A subclass of :class:`PurePath`, this path flavour represents Windows filesystem paths, including `UNC paths`_:: @@ -175,7 +175,7 @@ we also call *flavours*: >>> PureWindowsPath('//server/share/file') PureWindowsPath('//server/share/file') - *pathcomponents* is specified similarly to :class:`PurePath`. + *pathsegments* is specified similarly to :class:`PurePath`. .. _unc paths: https://en.wikipedia.org/wiki/Path_(computing)#UNC @@ -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(*pathcomponents) +.. class:: Path(*pathsegments) A subclass of :class:`PurePath`, this class represents concrete paths of the system's path flavour (instantiating it creates either a @@ -698,9 +698,9 @@ calls on path objects. There are three ways to instantiate concrete paths: >>> Path('setup.py') PosixPath('setup.py') - *pathcomponents* is specified similarly to :class:`PurePath`. + *pathsegments* is specified similarly to :class:`PurePath`. -.. class:: PosixPath(*pathcomponents) +.. class:: PosixPath(*pathsegments) A subclass of :class:`Path` and :class:`PurePosixPath`, this class represents concrete non-Windows filesystem paths:: @@ -708,9 +708,9 @@ calls on path objects. There are three ways to instantiate concrete paths: >>> PosixPath('/etc') PosixPath('/etc') - *pathcomponents* is specified similarly to :class:`PurePath`. + *pathsegments* is specified similarly to :class:`PurePath`. -.. class:: WindowsPath(*pathcomponents) +.. class:: WindowsPath(*pathsegments) A subclass of :class:`Path` and :class:`PureWindowsPath`, this class represents concrete Windows filesystem paths:: @@ -718,7 +718,7 @@ calls on path objects. There are three ways to instantiate concrete paths: >>> WindowsPath('c:/Program Files/') WindowsPath('c:/Program Files') - *pathcomponents* is specified similarly to :class:`PurePath`. + *pathsegments* 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 From 911049813ac77355160f9c89e9c70c9776c24aa0 Mon Sep 17 00:00:00 2001 From: hauntsaninja Date: Thu, 5 Jan 2023 16:49:54 -0800 Subject: [PATCH 5/7] revert segment --- Doc/library/pathlib.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 235deaaef50e0a..0432c6f08b4f77 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -118,7 +118,7 @@ we also call *flavours*: >>> PurePath() PurePosixPath('.') - If a component is an absolute path, all previous components are ignored + If a segment is an absolute path, all previous segments are ignored (like :func:`os.path.join`'):: >>> PurePath('/etc', '/usr', 'lib64') @@ -127,7 +127,7 @@ we also call *flavours*: PureWindowsPath('d:bar') On Windows, the drive is not reset when a drive-less absolute path - component (e.g., ``r'\foo'``) is encountered:: + segment (e.g., ``r'\foo'``) is encountered:: >>> PureWindowsPath('c:/Windows', '/Program Files') PureWindowsPath('c:/Program Files') @@ -213,9 +213,9 @@ Operators ^^^^^^^^^ The slash operator helps create child paths, like :func:`os.path.join`. -If the argument is an absolute path, the previous path components are ignored. -On Windows, the drive is not reset when a drive-less absolute path -component (e.g., ``r'\foo'``) is encountered:: +If the argument is an absolute path, the previous path is ignored. +On Windows, the drive is not reset when the argument is a drive-less +absolute path (e.g., ``r'\foo'``):: >>> p = PurePath('/etc') >>> p From ee484ba1b3afb27564fd11a0379e019e3dbffd6f Mon Sep 17 00:00:00 2001 From: Shantanu <12621235+hauntsaninja@users.noreply.github.com> Date: Thu, 5 Jan 2023 17:15:35 -0800 Subject: [PATCH 6/7] Apply suggestions from code review Co-authored-by: Barney Gale --- Doc/library/pathlib.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 0432c6f08b4f77..3563f22d7a0ebc 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -126,7 +126,7 @@ we also call *flavours*: >>> PureWindowsPath('c:/Windows', 'd:bar') PureWindowsPath('d:bar') - On Windows, the drive is not reset when a drive-less absolute path + On Windows, the drive is not reset when a rooted relative path segment (e.g., ``r'\foo'``) is encountered:: >>> PureWindowsPath('c:/Windows', '/Program Files') @@ -214,8 +214,8 @@ Operators The slash operator helps create child paths, like :func:`os.path.join`. If the argument is an absolute path, the previous path is ignored. -On Windows, the drive is not reset when the argument is a drive-less -absolute path (e.g., ``r'\foo'``):: +On Windows, the drive is not reset when the argument is a rooted +relative path (e.g., ``r'\foo'``):: >>> p = PurePath('/etc') >>> p From 05fe8ddd208b7c692cde490507cf127040f8641a Mon Sep 17 00:00:00 2001 From: Shantanu <12621235+hauntsaninja@users.noreply.github.com> Date: Thu, 5 Jan 2023 17:22:33 -0800 Subject: [PATCH 7/7] Update Doc/library/pathlib.rst Co-authored-by: Barney Gale --- 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 3563f22d7a0ebc..c5cf409f5f1f81 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -119,7 +119,7 @@ we also call *flavours*: PurePosixPath('.') If a segment is an absolute path, all previous segments are ignored - (like :func:`os.path.join`'):: + (like :func:`os.path.join`):: >>> PurePath('/etc', '/usr', 'lib64') PurePosixPath('/usr/lib64')