diff --git a/Lib/pathlib.py b/Lib/pathlib.py
index bb440c9d57216a..7d0086e145f499 100644
--- a/Lib/pathlib.py
+++ b/Lib/pathlib.py
@@ -8,6 +8,7 @@
import sys
import warnings
from _collections_abc import Sequence
+from abc import ABC, abstractmethod
from errno import ENOENT, ENOTDIR, EBADF, ELOOP
from operator import attrgetter
from stat import S_ISDIR, S_ISLNK, S_ISREG, S_ISSOCK, S_ISBLK, S_ISCHR, S_ISFIFO
@@ -392,7 +393,7 @@ def __repr__(self):
return "<{}.parents>".format(self._pathcls.__name__)
-class PurePath(object):
+class PurePath(os.PathLike):
"""Base class for manipulating paths without I/O.
PurePath represents a filesystem path and offers operations which
@@ -473,6 +474,12 @@ def _make_child(self, args):
self._drv, self._root, self._parts, drv, root, parts)
return self._from_parsed_parts(drv, root, parts)
+ def _make_child_relpath(self, part):
+ # This is an optimization used for dir walking. `part` must be
+ # a single part relative to this path.
+ parts = self._parts + [part]
+ return self._from_parsed_parts(self._drv, self._root, parts)
+
def __str__(self):
"""Return the string representation of the path, suitable for
passing to system calls."""
@@ -766,10 +773,6 @@ def match(self, path_pattern):
return False
return True
-# Can't subclass os.PathLike from PurePath and keep the constructor
-# optimizations in PurePath._parse_args().
-os.PathLike.register(PurePath)
-
class PurePosixPath(PurePath):
"""PurePath subclass for non-Windows systems.
@@ -794,65 +797,12 @@ class PureWindowsPath(PurePath):
# Filesystem-accessing classes
-class Path(PurePath):
- """PurePath subclass that can make system calls.
-
- Path represents a filesystem path but unlike PurePath, also offers
- methods to do system calls on path objects. Depending on your system,
- instantiating a Path will return either a PosixPath or a WindowsPath
- object. You can also instantiate a PosixPath or WindowsPath directly,
- but cannot instantiate a WindowsPath on a POSIX system or vice versa.
+class _AbstractPath(PurePath, ABC):
+ """Private PurePath subclass with abstract methods for opening files and
+ listing directories.
"""
__slots__ = ()
- def __new__(cls, *args, **kwargs):
- if cls is Path:
- cls = WindowsPath if os.name == 'nt' else PosixPath
- self = cls._from_parts(args)
- if not self._flavour.is_supported:
- raise NotImplementedError("cannot instantiate %r on your system"
- % (cls.__name__,))
- return self
-
- def _make_child_relpath(self, part):
- # This is an optimization used for dir walking. `part` must be
- # a single part relative to this path.
- parts = self._parts + [part]
- return self._from_parsed_parts(self._drv, self._root, parts)
-
- def __enter__(self):
- # In previous versions of pathlib, __exit__() marked this path as
- # closed; subsequent attempts to perform I/O would raise an IOError.
- # This functionality was never documented, and had the effect of
- # making Path objects mutable, contrary to PEP 428.
- # In Python 3.9 __exit__() was made a no-op.
- # In Python 3.11 __enter__() began emitting DeprecationWarning.
- # In Python 3.13 __enter__() and __exit__() should be removed.
- warnings.warn("pathlib.Path.__enter__() is deprecated and scheduled "
- "for removal in Python 3.13; Path objects as a context "
- "manager is a no-op",
- DeprecationWarning, stacklevel=2)
- return self
-
- def __exit__(self, t, v, tb):
- pass
-
- # Public API
-
- @classmethod
- def cwd(cls):
- """Return a new path pointing to the current working directory
- (as returned by os.getcwd()).
- """
- return cls(os.getcwd())
-
- @classmethod
- def home(cls):
- """Return a new path pointing to the user's home directory (as
- returned by os.path.expanduser('~')).
- """
- return cls("~").expanduser()
-
def samefile(self, other_path):
"""Return whether other_path is the same or not as this file
(as returned by os.path.samefile()).
@@ -864,18 +814,19 @@ def samefile(self, other_path):
other_st = self.__class__(other_path).stat()
return os.path.samestat(st, other_st)
+ @abstractmethod
def iterdir(self):
"""Iterate over the files in this directory. Does not yield any
result for the special paths '.' and '..'.
"""
- for name in os.listdir(self):
- yield self._make_child_relpath(name)
+ raise NotImplementedError
def _scandir(self):
- # bpo-24132: a future version of pathlib will support subclassing of
- # pathlib.Path to customize how the filesystem is accessed. This
- # includes scandir(), which is used to implement glob().
- return os.scandir(self)
+ # This method is used to implement glob(). It yields os.DirEntry-like
+ # objects with some stat() data pre-cached. As the AbstractPath API is
+ # a superset of the DirEntry API, the default implementation forwards
+ # to iterdir() as a convenience.
+ return self.iterdir()
def glob(self, pattern):
"""Iterate over this subtree and yield all existing files (of any
@@ -908,80 +859,22 @@ def rglob(self, pattern):
for p in selector.select_from(self):
yield p
- def absolute(self):
- """Return an absolute version of this path by prepending the current
- working directory. No normalization or symlink resolution is performed.
-
- Use resolve() to get the canonical path to a file.
- """
- if self.is_absolute():
- return self
- return self._from_parts([self.cwd()] + self._parts)
-
- def resolve(self, strict=False):
- """
- Make the path absolute, resolving all symlinks on the way and also
- normalizing it.
- """
-
- def check_eloop(e):
- winerror = getattr(e, 'winerror', 0)
- if e.errno == ELOOP or winerror == _WINERROR_CANT_RESOLVE_FILENAME:
- raise RuntimeError("Symlink loop from %r" % e.filename)
-
- try:
- s = os.path.realpath(self, strict=strict)
- except OSError as e:
- check_eloop(e)
- raise
- p = self._from_parts((s,))
-
- # In non-strict mode, realpath() doesn't raise on symlink loops.
- # Ensure we get an exception by calling stat()
- if not strict:
- try:
- p.stat()
- except OSError as e:
- check_eloop(e)
- return p
-
+ @abstractmethod
def stat(self, *, follow_symlinks=True):
"""
Return the result of the stat() system call on this path, like
os.stat() does.
"""
- return os.stat(self, follow_symlinks=follow_symlinks)
-
- def owner(self):
- """
- Return the login name of the file owner.
- """
- try:
- import pwd
- return pwd.getpwuid(self.stat().st_uid).pw_name
- except ImportError:
- raise NotImplementedError("Path.owner() is unsupported on this system")
-
- def group(self):
- """
- Return the group name of the file gid.
- """
-
- try:
- import grp
- return grp.getgrgid(self.stat().st_gid).gr_name
- except ImportError:
- raise NotImplementedError("Path.group() is unsupported on this system")
+ raise NotImplementedError
+ @abstractmethod
def open(self, mode='r', buffering=-1, encoding=None,
errors=None, newline=None):
"""
Open the file pointed by this path and return a file object, as
the built-in open() function does.
"""
- if "b" not in mode:
- encoding = io.text_encoding(encoding)
- return io.open(self, mode, buffering, encoding, errors, newline)
+ raise NotImplementedError
def read_bytes(self):
"""
@@ -1018,83 +911,6 @@ def write_text(self, data, encoding=None, errors=None, newline=None):
with self.open(mode='w', encoding=encoding, errors=errors, newline=newline) as f:
return f.write(data)
- def readlink(self):
- """
- Return the path to which the symbolic link points.
- """
- if not hasattr(os, "readlink"):
- raise NotImplementedError("os.readlink() not available on this system")
- return self._from_parts((os.readlink(self),))
-
- def touch(self, mode=0o666, exist_ok=True):
- """
- Create this file with the given access mode, if it doesn't exist.
- """
-
- if exist_ok:
- # First try to bump modification time
- # Implementation note: GNU touch uses the UTIME_NOW option of
- # the utimensat() / futimens() functions.
- try:
- os.utime(self, None)
- except OSError:
- # Avoid exception chaining
- pass
- else:
- return
- flags = os.O_CREAT | os.O_WRONLY
- if not exist_ok:
- flags |= os.O_EXCL
- fd = os.open(self, flags, mode)
- os.close(fd)
-
- def mkdir(self, mode=0o777, parents=False, exist_ok=False):
- """
- Create a new directory at this given path.
- """
- try:
- os.mkdir(self, mode)
- except FileNotFoundError:
- if not parents or self.parent == self:
- raise
- self.parent.mkdir(parents=True, exist_ok=True)
- self.mkdir(mode, parents=False, exist_ok=exist_ok)
- except OSError:
- # Cannot rely on checking for EEXIST, since the operating system
- # could give priority to other errors like EACCES or EROFS
- if not exist_ok or not self.is_dir():
- raise
-
- def chmod(self, mode, *, follow_symlinks=True):
- """
- Change the permissions of the path, like os.chmod().
- """
- os.chmod(self, mode, follow_symlinks=follow_symlinks)
-
- def lchmod(self, mode):
- """
- Like chmod(), except if the path points to a symlink, the symlink's
- permissions are changed, rather than its target's.
- """
- self.chmod(mode, follow_symlinks=False)
-
- def unlink(self, missing_ok=False):
- """
- Remove this file or link.
- If the path is a directory, use rmdir() instead.
- """
- try:
- os.unlink(self)
- except FileNotFoundError:
- if not missing_ok:
- raise
-
- def rmdir(self):
- """
- Remove this directory. The directory must be empty.
- """
- os.rmdir(self)
-
def lstat(self):
"""
Like stat(), except if the path points to a symlink, the symlink's
@@ -1102,52 +918,6 @@ def lstat(self):
"""
return self.stat(follow_symlinks=False)
- def rename(self, target):
- """
- Rename this path to the target path.
-
- The target path may be absolute or relative. Relative paths are
- interpreted relative to the current working directory, *not* the
- directory of the Path object.
-
- Returns the new Path instance pointing to the target path.
- """
- os.rename(self, target)
- return self.__class__(target)
-
- def replace(self, target):
- """
- Rename this path to the target path, overwriting if that path exists.
-
- The target path may be absolute or relative. Relative paths are
- interpreted relative to the current working directory, *not* the
- directory of the Path object.
-
- Returns the new Path instance pointing to the target path.
- """
- os.replace(self, target)
- return self.__class__(target)
-
- def symlink_to(self, target, target_is_directory=False):
- """
- Make this path a symlink pointing to the target path.
- Note the order of arguments (link, target) is the reverse of os.symlink.
- """
- if not hasattr(os, "symlink"):
- raise NotImplementedError("os.symlink() not available on this system")
- os.symlink(target, self, target_is_directory)
-
- def hardlink_to(self, target):
- """
- Make this path a hard link pointing to the same file as *target*.
-
- Note the order of arguments (self, target) is the reverse of os.link's.
- """
- if not hasattr(os, "link"):
- raise NotImplementedError("os.link() not available on this system")
- os.link(target, self)
-
-
# Convenience functions for querying the stat results
def exists(self):
@@ -1297,6 +1067,256 @@ def is_socket(self):
# Non-encodable path
return False
+
+class Path(_AbstractPath):
+ """PurePath subclass that can make system calls.
+
+ Path represents a filesystem path but unlike PurePath, also offers
+ methods to do system calls on path objects. Depending on your system,
+ instantiating a Path will return either a PosixPath or a WindowsPath
+ object. You can also instantiate a PosixPath or WindowsPath directly,
+ but cannot instantiate a WindowsPath on a POSIX system or vice versa.
+ """
+ __slots__ = ()
+
+ def __new__(cls, *args, **kwargs):
+ if cls is Path:
+ cls = WindowsPath if os.name == 'nt' else PosixPath
+ self = cls._from_parts(args)
+ if not self._flavour.is_supported:
+ raise NotImplementedError("cannot instantiate %r on your system"
+ % (cls.__name__,))
+ return self
+
+ def __enter__(self):
+ # In previous versions of pathlib, __exit__() marked this path as
+ # closed; subsequent attempts to perform I/O would raise an IOError.
+ # This functionality was never documented, and had the effect of
+ # making Path objects mutable, contrary to PEP 428.
+ # In Python 3.9 __exit__() was made a no-op.
+ # In Python 3.11 __enter__() began emitting DeprecationWarning.
+ # In Python 3.13 __enter__() and __exit__() should be removed.
+ warnings.warn("pathlib.Path.__enter__() is deprecated and scheduled "
+ "for removal in Python 3.13; Path objects as a context "
+ "manager is a no-op",
+ DeprecationWarning, stacklevel=2)
+ return self
+
+ def __exit__(self, t, v, tb):
+ pass
+
+ # Public API
+
+ @classmethod
+ def cwd(cls):
+ """Return a new path pointing to the current working directory
+ (as returned by os.getcwd()).
+ """
+ return cls(os.getcwd())
+
+ @classmethod
+ def home(cls):
+ """Return a new path pointing to the user's home directory (as
+ returned by os.path.expanduser('~')).
+ """
+ return cls("~").expanduser()
+
+ def iterdir(self):
+ for name in os.listdir(self):
+ yield self._make_child_relpath(name)
+
+ def _scandir(self):
+ return os.scandir(self)
+
+ def absolute(self):
+ """Return an absolute version of this path by prepending the current
+ working directory. No normalization or symlink resolution is performed.
+
+ Use resolve() to get the canonical path to a file.
+ """
+ if self.is_absolute():
+ return self
+ return self._from_parts([self.cwd()] + self._parts)
+
+ def resolve(self, strict=False):
+ """
+ Make the path absolute, resolving all symlinks on the way and also
+ normalizing it.
+ """
+
+ def check_eloop(e):
+ winerror = getattr(e, 'winerror', 0)
+ if e.errno == ELOOP or winerror == _WINERROR_CANT_RESOLVE_FILENAME:
+ raise RuntimeError("Symlink loop from %r" % e.filename)
+
+ try:
+ s = os.path.realpath(self, strict=strict)
+ except OSError as e:
+ check_eloop(e)
+ raise
+ p = self._from_parts((s,))
+
+ # In non-strict mode, realpath() doesn't raise on symlink loops.
+ # Ensure we get an exception by calling stat()
+ if not strict:
+ try:
+ p.stat()
+ except OSError as e:
+ check_eloop(e)
+ return p
+
+ def stat(self, *, follow_symlinks=True):
+ return os.stat(self, follow_symlinks=follow_symlinks)
+
+ def owner(self):
+ """
+ Return the login name of the file owner.
+ """
+ try:
+ import pwd
+ return pwd.getpwuid(self.stat().st_uid).pw_name
+ except ImportError:
+ raise NotImplementedError("Path.owner() is unsupported on this system")
+
+ def group(self):
+ """
+ Return the group name of the file gid.
+ """
+
+ try:
+ import grp
+ return grp.getgrgid(self.stat().st_gid).gr_name
+ except ImportError:
+ raise NotImplementedError("Path.group() is unsupported on this system")
+
+ def open(self, mode='r', buffering=-1, encoding=None,
+ errors=None, newline=None):
+ if "b" not in mode:
+ encoding = io.text_encoding(encoding)
+ return io.open(self, mode, buffering, encoding, errors, newline)
+
+ def readlink(self):
+ """
+ Return the path to which the symbolic link points.
+ """
+ if not hasattr(os, "readlink"):
+ raise NotImplementedError("os.readlink() not available on this system")
+ return self._from_parts((os.readlink(self),))
+
+ def touch(self, mode=0o666, exist_ok=True):
+ """
+ Create this file with the given access mode, if it doesn't exist.
+ """
+
+ if exist_ok:
+ # First try to bump modification time
+ # Implementation note: GNU touch uses the UTIME_NOW option of
+ # the utimensat() / futimens() functions.
+ try:
+ os.utime(self, None)
+ except OSError:
+ # Avoid exception chaining
+ pass
+ else:
+ return
+ flags = os.O_CREAT | os.O_WRONLY
+ if not exist_ok:
+ flags |= os.O_EXCL
+ fd = os.open(self, flags, mode)
+ os.close(fd)
+
+ def mkdir(self, mode=0o777, parents=False, exist_ok=False):
+ """
+ Create a new directory at this given path.
+ """
+ try:
+ os.mkdir(self, mode)
+ except FileNotFoundError:
+ if not parents or self.parent == self:
+ raise
+ self.parent.mkdir(parents=True, exist_ok=True)
+ self.mkdir(mode, parents=False, exist_ok=exist_ok)
+ except OSError:
+ # Cannot rely on checking for EEXIST, since the operating system
+ # could give priority to other errors like EACCES or EROFS
+ if not exist_ok or not self.is_dir():
+ raise
+
+ def chmod(self, mode, *, follow_symlinks=True):
+ """
+ Change the permissions of the path, like os.chmod().
+ """
+ os.chmod(self, mode, follow_symlinks=follow_symlinks)
+
+ def lchmod(self, mode):
+ """
+ Like chmod(), except if the path points to a symlink, the symlink's
+ permissions are changed, rather than its target's.
+ """
+ self.chmod(mode, follow_symlinks=False)
+
+ def unlink(self, missing_ok=False):
+ """
+ Remove this file or link.
+ If the path is a directory, use rmdir() instead.
+ """
+ try:
+ os.unlink(self)
+ except FileNotFoundError:
+ if not missing_ok:
+ raise
+
+ def rmdir(self):
+ """
+ Remove this directory. The directory must be empty.
+ """
+ os.rmdir(self)
+
+ def rename(self, target):
+ """
+ Rename this path to the target path.
+
+ The target path may be absolute or relative. Relative paths are
+ interpreted relative to the current working directory, *not* the
+ directory of the Path object.
+
+ Returns the new Path instance pointing to the target path.
+ """
+ os.rename(self, target)
+ return self.__class__(target)
+
+ def replace(self, target):
+ """
+ Rename this path to the target path, overwriting if that path exists.
+
+ The target path may be absolute or relative. Relative paths are
+ interpreted relative to the current working directory, *not* the
+ directory of the Path object.
+
+ Returns the new Path instance pointing to the target path.
+ """
+ os.replace(self, target)
+ return self.__class__(target)
+
+ def symlink_to(self, target, target_is_directory=False):
+ """
+ Make this path a symlink pointing to the target path.
+ Note the order of arguments (link, target) is the reverse of os.symlink.
+ """
+ if not hasattr(os, "symlink"):
+ raise NotImplementedError("os.symlink() not available on this system")
+ os.symlink(target, self, target_is_directory)
+
+ def hardlink_to(self, target):
+ """
+ Make this path a hard link pointing to the same file as *target*.
+
+ Note the order of arguments (self, target) is the reverse of os.link's.
+ """
+ if not hasattr(os, "link"):
+ raise NotImplementedError("os.link() not available on this system")
+ os.link(target, self)
+
def expanduser(self):
""" Return a new path with expanded ~ and ~user constructs
(as returned by os.path.expanduser)
diff --git a/Misc/NEWS.d/next/Library/2022-02-02-18-59-09.bpo-24132.mddFFe.rst b/Misc/NEWS.d/next/Library/2022-02-02-18-59-09.bpo-24132.mddFFe.rst
new file mode 100644
index 00000000000000..21daca18ee97db
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2022-02-02-18-59-09.bpo-24132.mddFFe.rst
@@ -0,0 +1,2 @@
+Add :class:`pathlib._AbstractPath` class. This internal class sets the stage
+for supporting user-defined path subclasses in a future version of Python.