Skip to content

Commit

Permalink
pythonGH-100479: Add pathlib.PurePath.with_segments() (pythonGH-103975
Browse files Browse the repository at this point in the history
)

Add `pathlib.PurePath.with_segments()`, which creates a path object from arguments. This method is called whenever a derivative path is created, such as from `pathlib.PurePath.parent`. Subclasses may override this method to share information between path objects.

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
  • Loading branch information
2 people authored and jbower-fb committed May 8, 2023
1 parent ef989ab commit 0b62e96
Show file tree
Hide file tree
Showing 5 changed files with 108 additions and 47 deletions.
28 changes: 26 additions & 2 deletions Doc/library/pathlib.rst
Original file line number Diff line number Diff line change
Expand Up @@ -530,10 +530,10 @@ Pure paths provide the following methods and properties:
unintended effects.


.. method:: PurePath.joinpath(*other)
.. method:: PurePath.joinpath(*pathsegments)

Calling this method is equivalent to combining the path with each of
the *other* arguments in turn::
the given *pathsegments* in turn::

>>> PurePosixPath('/etc').joinpath('passwd')
PurePosixPath('/etc/passwd')
Expand Down Expand Up @@ -680,6 +680,30 @@ Pure paths provide the following methods and properties:
PureWindowsPath('README')


.. method:: PurePath.with_segments(*pathsegments)

Create a new path object of the same type by combining the given
*pathsegments*. This method is called whenever a derivative path is created,
such as from :attr:`parent` and :meth:`relative_to`. Subclasses may
override this method to pass information to derivative paths, for example::

from pathlib import PurePosixPath

class MyPath(PurePosixPath):
def __init__(self, *pathsegments, session_id):
super().__init__(*pathsegments)
self.session_id = session_id

def with_segments(self, *pathsegments):
return type(self)(*pathsegments, session_id=self.session_id)

etc = MyPath('/etc', session_id=42)
hosts = etc / 'hosts'
print(hosts.session_id) # 42

.. versionadded:: 3.12


.. _concrete-paths:


Expand Down
5 changes: 5 additions & 0 deletions Doc/whatsnew/3.12.rst
Original file line number Diff line number Diff line change
Expand Up @@ -348,6 +348,11 @@ inspect
pathlib
-------

* Add support for subclassing :class:`pathlib.PurePath` and
:class:`~pathlib.Path`, plus their Posix- and Windows-specific variants.
Subclasses may override the :meth:`~pathlib.PurePath.with_segments` method
to pass information between path instances.

* Add :meth:`~pathlib.Path.walk` for walking the directory trees and generating
all file or directory names within them, similar to :func:`os.walk`.
(Contributed by Stanislav Zmiev in :gh:`90385`.)
Expand Down
66 changes: 36 additions & 30 deletions Lib/pathlib.py
Original file line number Diff line number Diff line change
Expand Up @@ -204,11 +204,10 @@ def _select_from(self, parent_path, scandir):
class _PathParents(Sequence):
"""This object provides sequence-like access to the logical ancestors
of a path. Don't try to construct it yourself."""
__slots__ = ('_pathcls', '_drv', '_root', '_tail')
__slots__ = ('_path', '_drv', '_root', '_tail')

def __init__(self, path):
# We don't store the instance to avoid reference cycles
self._pathcls = type(path)
self._path = path
self._drv = path.drive
self._root = path.root
self._tail = path._tail
Expand All @@ -224,11 +223,11 @@ def __getitem__(self, idx):
raise IndexError(idx)
if idx < 0:
idx += len(self)
return self._pathcls._from_parsed_parts(self._drv, self._root,
self._tail[:-idx - 1])
return self._path._from_parsed_parts(self._drv, self._root,
self._tail[:-idx - 1])

def __repr__(self):
return "<{}.parents>".format(self._pathcls.__name__)
return "<{}.parents>".format(type(self._path).__name__)


class PurePath(object):
Expand Down Expand Up @@ -316,6 +315,13 @@ def __init__(self, *args):
else:
self._raw_path = self._flavour.join(*paths)

def with_segments(self, *pathsegments):
"""Construct a new path object from any number of path-like objects.
Subclasses may override this method to customize how new path objects
are created from methods like `iterdir()`.
"""
return type(self)(*pathsegments)

@classmethod
def _parse_path(cls, path):
if not path:
Expand All @@ -342,15 +348,14 @@ def _load_parts(self):
self._root = root
self._tail_cached = tail

@classmethod
def _from_parsed_parts(cls, drv, root, tail):
path = cls._format_parsed_parts(drv, root, tail)
self = cls(path)
self._str = path or '.'
self._drv = drv
self._root = root
self._tail_cached = tail
return self
def _from_parsed_parts(self, drv, root, tail):
path_str = self._format_parsed_parts(drv, root, tail)
path = self.with_segments(path_str)
path._str = path_str or '.'
path._drv = drv
path._root = root
path._tail_cached = tail
return path

@classmethod
def _format_parsed_parts(cls, drv, root, tail):
Expand Down Expand Up @@ -584,8 +589,7 @@ def relative_to(self, other, /, *_deprecated, walk_up=False):
"scheduled for removal in Python {remove}")
warnings._deprecated("pathlib.PurePath.relative_to(*args)", msg,
remove=(3, 14))
path_cls = type(self)
other = path_cls(other, *_deprecated)
other = self.with_segments(other, *_deprecated)
for step, path in enumerate([other] + list(other.parents)):
if self.is_relative_to(path):
break
Expand All @@ -594,7 +598,7 @@ def relative_to(self, other, /, *_deprecated, walk_up=False):
if step and not walk_up:
raise ValueError(f"{str(self)!r} is not in the subpath of {str(other)!r}")
parts = ['..'] * step + self._tail[len(path._tail):]
return path_cls(*parts)
return self.with_segments(*parts)

def is_relative_to(self, other, /, *_deprecated):
"""Return True if the path is relative to another path or False.
Expand All @@ -605,7 +609,7 @@ def is_relative_to(self, other, /, *_deprecated):
"scheduled for removal in Python {remove}")
warnings._deprecated("pathlib.PurePath.is_relative_to(*args)",
msg, remove=(3, 14))
other = type(self)(other, *_deprecated)
other = self.with_segments(other, *_deprecated)
return other == self or other in self.parents

@property
Expand All @@ -617,13 +621,13 @@ def parts(self):
else:
return tuple(self._tail)

def joinpath(self, *args):
def joinpath(self, *pathsegments):
"""Combine this path with one or several arguments, and return a
new path representing either a subpath (if all arguments are relative
paths) or a totally different path (if one of the arguments is
anchored).
"""
return self.__class__(self, *args)
return self.with_segments(self, *pathsegments)

def __truediv__(self, key):
try:
Expand All @@ -633,7 +637,7 @@ def __truediv__(self, key):

def __rtruediv__(self, key):
try:
return type(self)(key, self)
return self.with_segments(key, self)
except TypeError:
return NotImplemented

Expand All @@ -650,6 +654,8 @@ def parent(self):
@property
def parents(self):
"""A sequence of this path's logical parents."""
# The value of this property should not be cached on the path object,
# as doing so would introduce a reference cycle.
return _PathParents(self)

def is_absolute(self):
Expand Down Expand Up @@ -680,7 +686,7 @@ def match(self, path_pattern):
"""
Return True if this path matches the given pattern.
"""
pat = type(self)(path_pattern)
pat = self.with_segments(path_pattern)
if not pat.parts:
raise ValueError("empty pattern")
pat_parts = pat._parts_normcase
Expand Down Expand Up @@ -755,7 +761,7 @@ def _make_child_relpath(self, name):
path_str = f'{path_str}{name}'
else:
path_str = name
path = type(self)(path_str)
path = self.with_segments(path_str)
path._str = path_str
path._drv = self.drive
path._root = self.root
Expand Down Expand Up @@ -805,7 +811,7 @@ def samefile(self, other_path):
try:
other_st = other_path.stat()
except AttributeError:
other_st = self.__class__(other_path).stat()
other_st = self.with_segments(other_path).stat()
return self._flavour.samestat(st, other_st)

def iterdir(self):
Expand Down Expand Up @@ -867,7 +873,7 @@ def absolute(self):
cwd = self._flavour.abspath(self.drive)
else:
cwd = os.getcwd()
return type(self)(cwd, self)
return self.with_segments(cwd, self)

def resolve(self, strict=False):
"""
Expand All @@ -885,7 +891,7 @@ def check_eloop(e):
except OSError as e:
check_eloop(e)
raise
p = type(self)(s)
p = self.with_segments(s)

# In non-strict mode, realpath() doesn't raise on symlink loops.
# Ensure we get an exception by calling stat()
Expand Down Expand Up @@ -975,7 +981,7 @@ def readlink(self):
"""
if not hasattr(os, "readlink"):
raise NotImplementedError("os.readlink() not available on this system")
return type(self)(os.readlink(self))
return self.with_segments(os.readlink(self))

def touch(self, mode=0o666, exist_ok=True):
"""
Expand Down Expand Up @@ -1064,7 +1070,7 @@ def rename(self, target):
Returns the new Path instance pointing to the target path.
"""
os.rename(self, target)
return self.__class__(target)
return self.with_segments(target)

def replace(self, target):
"""
Expand All @@ -1077,7 +1083,7 @@ def replace(self, target):
Returns the new Path instance pointing to the target path.
"""
os.replace(self, target)
return self.__class__(target)
return self.with_segments(target)

def symlink_to(self, target, target_is_directory=False):
"""
Expand Down
52 changes: 37 additions & 15 deletions Lib/test/test_pathlib.py
Original file line number Diff line number Diff line change
Expand Up @@ -29,11 +29,12 @@
#

class _BasePurePathSubclass(object):
init_called = False
def __init__(self, *pathsegments, session_id):
super().__init__(*pathsegments)
self.session_id = session_id

def __init__(self, *args):
super().__init__(*args)
self.init_called = True
def with_segments(self, *pathsegments):
return type(self)(*pathsegments, session_id=self.session_id)


class _BasePurePathTest(object):
Expand Down Expand Up @@ -121,20 +122,21 @@ def test_str_subclass_common(self):
self._check_str_subclass('a/b.txt')
self._check_str_subclass('/a/b.txt')

def test_init_called_common(self):
def test_with_segments_common(self):
class P(_BasePurePathSubclass, self.cls):
pass
p = P('foo', 'bar')
self.assertTrue((p / 'foo').init_called)
self.assertTrue(('foo' / p).init_called)
self.assertTrue(p.joinpath('foo').init_called)
self.assertTrue(p.with_name('foo').init_called)
self.assertTrue(p.with_stem('foo').init_called)
self.assertTrue(p.with_suffix('.foo').init_called)
self.assertTrue(p.relative_to('foo').init_called)
self.assertTrue(p.parent.init_called)
p = P('foo', 'bar', session_id=42)
self.assertEqual(42, (p / 'foo').session_id)
self.assertEqual(42, ('foo' / p).session_id)
self.assertEqual(42, p.joinpath('foo').session_id)
self.assertEqual(42, p.with_name('foo').session_id)
self.assertEqual(42, p.with_stem('foo').session_id)
self.assertEqual(42, p.with_suffix('.foo').session_id)
self.assertEqual(42, p.with_segments('foo').session_id)
self.assertEqual(42, p.relative_to('foo').session_id)
self.assertEqual(42, p.parent.session_id)
for parent in p.parents:
self.assertTrue(parent.init_called)
self.assertEqual(42, parent.session_id)

def _get_drive_root_parts(self, parts):
path = self.cls(*parts)
Expand Down Expand Up @@ -1647,6 +1649,26 @@ def test_home(self):
env['HOME'] = os.path.join(BASE, 'home')
self._test_home(self.cls.home())

def test_with_segments(self):
class P(_BasePurePathSubclass, self.cls):
pass
p = P(BASE, session_id=42)
self.assertEqual(42, p.absolute().session_id)
self.assertEqual(42, p.resolve().session_id)
self.assertEqual(42, p.with_segments('~').expanduser().session_id)
self.assertEqual(42, (p / 'fileA').rename(p / 'fileB').session_id)
self.assertEqual(42, (p / 'fileB').replace(p / 'fileA').session_id)
if os_helper.can_symlink():
self.assertEqual(42, (p / 'linkA').readlink().session_id)
for path in p.iterdir():
self.assertEqual(42, path.session_id)
for path in p.glob('*'):
self.assertEqual(42, path.session_id)
for path in p.rglob('*'):
self.assertEqual(42, path.session_id)
for dirpath, dirnames, filenames in p.walk():
self.assertEqual(42, dirpath.session_id)

def test_samefile(self):
fileA_path = os.path.join(BASE, 'fileA')
fileB_path = os.path.join(BASE, 'dirB', 'fileB')
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
Add :meth:`pathlib.PurePath.with_segments`, which creates a path object from
arguments. This method is called whenever a derivative path is created, such
as from :attr:`pathlib.PurePath.parent`. Subclasses may override this method
to share information between path objects.

0 comments on commit 0b62e96

Please sign in to comment.