GH-100479: Add optional blueprint argument to pathlib.PurePath

Doc/library/pathlib.rst

@@ -359,8 +359,7 @@ Pure paths provide the following methods and properties:
 
 .. attribute:: PurePath.parents
 
-   An immutable sequence providing access to the logical ancestors of
-   the path::
+   A tuple providing access to the logical ancestors of the path::
 
       >>> p = PureWindowsPath('c:/foo/bar/setup.py')
       >>> p.parents[0]
@@ -373,6 +372,9 @@ Pure paths provide the following methods and properties:
    .. versionchanged:: 3.10
       The parents sequence now supports :term:`slices <slice>` and negative index values.
 
+   .. versionchanged:: 3.12
+      Type changed from a tuple-like immutable sequence to a true tuple.
+
 .. attribute:: PurePath.parent
 
    The logical parent of the path::
@@ -545,6 +547,30 @@ Pure paths provide the following methods and properties:
       PureWindowsPath('c:/Program Files')
 
 
+.. method:: PurePath.makepath(*other)
+
+   Create a new path object of the same type by combining the *other*
+   arguments. 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, *args, session_id):
+              super().__init__(*args)
+              self.session_id = session_id
+
+          def makepath(self, *other):
+              return type(self)(*other, session_id=self.session_id)
+
+      etc = MyPath('/etc', session_id=42)
+      hosts = etc / 'hosts'
+      print(hosts.session_id)  # 42
+
+   .. versionadded:: 3.12
+
+
 .. method:: PurePath.match(pattern)
 
    Match this path against the provided glob-style pattern.  Return ``True``

Lib/pathlib.py

@@ -14,7 +14,6 @@
 import re
 import sys
 import warnings
-from _collections_abc import Sequence
 from errno import ENOENT, ENOTDIR, EBADF, ELOOP
 from stat import S_ISDIR, S_ISLNK, S_ISREG, S_ISSOCK, S_ISBLK, S_ISCHR, S_ISFIFO
 from urllib.parse import quote_from_bytes as urlquote_from_bytes
@@ -207,39 +206,6 @@ def _select_from(self, parent_path, is_dir, exists, scandir, normcase):
 # Public API
 #
 
-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', '_parts')
-
-    def __init__(self, path):
-        # We don't store the instance to avoid reference cycles
-        self._pathcls = type(path)
-        self._drv = path.drive
-        self._root = path.root
-        self._parts = path._parts
-
-    def __len__(self):
-        if self._drv or self._root:
-            return len(self._parts) - 1
-        else:
-            return len(self._parts)
-
-    def __getitem__(self, idx):
-        if isinstance(idx, slice):
-            return tuple(self[i] for i in range(*idx.indices(len(self))))
-
-        if idx >= len(self) or idx < -len(self):
-            raise IndexError(idx)
-        if idx < 0:
-            idx += len(self)
-        return self._pathcls._from_parsed_parts(self._drv, self._root,
-                                                self._parts[:-idx - 1])
-
-    def __repr__(self):
-        return "<{}.parents>".format(self._pathcls.__name__)
-
-
 class PurePath(object):
     """Base class for manipulating paths without I/O.
 
@@ -309,15 +275,14 @@ def _load_parts(self):
         self._root = root
         self._parts_cached = parts
 
-    @classmethod
-    def _from_parsed_parts(cls, drv, root, parts):
-        path = cls._format_parsed_parts(drv, root, parts)
-        self = cls(path)
-        self._str = path or '.'
-        self._drv = drv
-        self._root = root
-        self._parts_cached = parts
-        return self
+    def _from_parsed_parts(self, drv, root, parts):
+        path_str = self._format_parsed_parts(drv, root, parts)
+        path = self.makepath(path_str)
+        path._str = path_str or '.'
+        path._drv = drv
+        path._root = root
+        path._parts_cached = parts
+        return path
 
     @classmethod
     def _format_parsed_parts(cls, drv, root, parts):
@@ -542,8 +507,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.makepath(other, *_deprecated)
         for step, path in enumerate([other] + list(other.parents)):
             if self.is_relative_to(path):
                 break
@@ -552,7 +516,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.parts[len(path.parts):]
-        return path_cls(*parts)
+        return self.makepath(*parts)
 
     def is_relative_to(self, other, /, *_deprecated):
         """Return True if the path is relative to another path or False.
@@ -563,7 +527,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.makepath(other, *_deprecated)
         return other == self or other in self.parents
 
     @property
@@ -578,13 +542,20 @@ def parts(self):
             self._parts_tuple = tuple(self._parts)
             return self._parts_tuple
 
+    def makepath(self, *args):
+        """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)(*args)
+
     def joinpath(self, *args):
         """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._raw_path, *args)
+        return self.makepath(self._raw_path, *args)
 
     def __truediv__(self, key):
         try:
@@ -594,7 +565,7 @@ def __truediv__(self, key):
 
     def __rtruediv__(self, key):
         try:
-            return type(self)(key, self._raw_path)
+            return self.makepath(key, self._raw_path)
         except TypeError:
             return NotImplemented
 
@@ -604,14 +575,19 @@ def parent(self):
         drv = self.drive
         root = self.root
         parts = self._parts
-        if len(parts) == 1 and (drv or root):
+        if len(parts) == bool(drv or root):
             return self
         return self._from_parsed_parts(drv, root, parts[:-1])
 
     @property
     def parents(self):
-        """A sequence of this path's logical parents."""
-        return _PathParents(self)
+        """A tuple of this path's logical parents."""
+        drv = self.drive
+        root = self.root
+        parts = self._parts
+        return tuple(
+            self._from_parsed_parts(drv, root, parts[:idx])
+            for idx in reversed(range(bool(drv or root), len(parts))))
 
     def is_absolute(self):
         """True if the path is absolute (has both a root and, if applicable,
@@ -756,7 +732,7 @@ def samefile(self, other_path):
         try:
             other_st = other_path.stat()
         except AttributeError:
-            other_st = self.__class__(other_path).stat()
+            other_st = self.makepath(other_path).stat()
         return self._flavour.samestat(st, other_st)
 
     def iterdir(self):
@@ -818,7 +794,7 @@ def absolute(self):
             cwd = self._flavour.abspath(self.drive)
         else:
             cwd = os.getcwd()
-        return type(self)(cwd, self._raw_path)
+        return self.makepath(cwd, self._raw_path)
 
     def resolve(self, strict=False):
         """
@@ -836,7 +812,7 @@ def check_eloop(e):
         except OSError as e:
             check_eloop(e)
             raise
-        p = type(self)(s)
+        p = self.makepath(s)
 
         # In non-strict mode, realpath() doesn't raise on symlink loops.
         # Ensure we get an exception by calling stat()
@@ -926,7 +902,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.makepath(os.readlink(self))
 
     def touch(self, mode=0o666, exist_ok=True):
         """
@@ -1015,7 +991,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.makepath(target)
 
     def replace(self, target):
         """
@@ -1028,7 +1004,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.makepath(target)
 
     def symlink_to(self, target, target_is_directory=False):
         """

Lib/test/test_pathlib.py

@@ -139,11 +139,12 @@ def test_parse_parts(self):
 #
 
 class _BasePurePathSubclass(object):
-    init_called = False
-
-    def __init__(self, *args):
+    def __init__(self, *args, session_id):
         super().__init__(*args)
-        self.init_called = True
+        self.session_id = session_id
+
+    def makepath(self, *args):
+        return type(self)(*args, session_id=self.session_id)
 
 
 class _BasePurePathTest(object):
@@ -231,20 +232,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_makepath_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.makepath('foo').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.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 test_join_common(self):
         P = self.cls
@@ -1638,6 +1640,26 @@ def test_home(self):
             env['HOME'] = os.path.join(BASE, 'home')
             self._test_home(self.cls.home())
 
+    def test_makepath(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.makepath('~').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')

Misc/NEWS.d/next/Library/2023-04-03-22-02-35.gh-issue-100479.kNBjQm.rst

@@ -0,0 +1,4 @@
+Add :meth:`pathlib.PurePath.makepath`, 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 pass information to derivative paths.