diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 8ee89a003a339a..246dcba19edb6e 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -1591,6 +1591,118 @@ call fails (for example because the path doesn't exist). .. versionchanged:: 3.10 The *newline* parameter was added. + +Virtual paths +------------- + +.. class:: PurePathBase(*path_segments) + + Abstract base class for path objects without I/O support. + + The :class:`PurePath` class is a subclass of this class. + + Unlike :class:`PurePath`, this class does not define any of these + magic methods: + :meth:`~os.PathLike.__fspath__`, :meth:`~object.__bytes__`, + :meth:`~object.__reduce__`, + :meth:`~object.__hash__`, :meth:`~object.__eq__`, + :meth:`~object.__lt__`, :meth:`~object.__le__`, + :meth:`~object.__gt__`, :meth:`~object.__ge__`. + + .. versionadded:: 3.13 + + +.. class:: PathBase(*path_segments) + + Abstract base class for path objects with I/O support. + + This class provides abstract implementations for methods that derived + classes can override selectively; the default implementations raise + :exc:`UnsupportedOperation`. + + The :class:`Path` class is a subclass of this class that operates on the + local filesystem. User-defined subclasses may operate on other kinds of + filesystem, such as archive files or remote storage; instances of these + classes are *virtual paths*. + + Like its superclass :class:`PurePathBase` (and unlike :class:`PurePath` and + :class:`Path`), this class does not define these magic methods: + :meth:`~os.PathLike.__fspath__`, :meth:`~object.__bytes__`, + :meth:`~object.__reduce__`, + :meth:`~object.__hash__`, :meth:`~object.__eq__`, + :meth:`~object.__lt__`, :meth:`~object.__le__`, + :meth:`~object.__gt__`, :meth:`~object.__ge__`. + In all other respects, its interface is the same as :class:`Path`. + + The default implementations of the most basic methods, like ``stat()`` + and ``iterdir()``, directly raise :exc:`UnsupportedOperation`. Other + methods like ``is_dir()`` and ``glob()`` call through to the basic methods. + The following table shows their relationships: + + .. list-table:: + :header-rows: 1 + + * - Basic Methods + - Mixin Methods + * - ``stat()`` + - ``lstat()``, ``exists()``, ``resolve()``, ``samefile()``, + ``is_dir()``, ``is_file()``, ``is_mount()``, ``is_symlink()``, + ``is_block_device()``, ``is_char_device()``, ``is_fifo()``, + ``is_socket()`` + * - ``open()`` + - ``read_text()``, ``write_text()``, + ``read_bytes()``, ``write_bytes()`` + * - ``iterdir()`` and ``stat()`` + - ``glob()``, ``rglob()``, ``walk()`` + * - ``chmod()`` + - ``lchmod()`` + * - ``expanduser()`` + - ``home()`` + * - ``absolute()`` + - ``cwd()`` + * - ``symlink_to()``, ``hardlink_to()``, ``mkdir()``, ``touch()``, + ``rename()``, ``replace()``, ``unlink()``, ``rmdir()``, + ``owner()``, ``group()``, ``from_uri()``, ``as_uri()``, + ``is_junction()`` + - No mixin methods + + These methods are described in the documentation for + :ref:`concrete paths `. That said, some methods deserve + special attention: + + .. method:: stat(*, follow_symlinks=True) + + Returns information about the path. + + The default implementation of this method immediately raises + :exc:`UnsupportedOperation`. Subclasses that override this method should + return an object that resembles a :class:`~os.stat_result`; it should at + least have ``st_mode``, ``st_dev`` and ``st_ino`` attributes. + + .. method:: resolve(strict=False) + + Resolves symlinks and eliminates ``..`` path components. If supported, + make the path absolute. + + The default implementation of this method first calls + ``absolute()``, but suppresses any resulting :exc:`UnsupportedOperation` + exception; this allows paths to be resolved on filesystems that lack + a notion of a working directory. It calls ``stat()`` on each ancestor + path, and ``readlink()`` when a stat result indicates a symlink. + :exc:`OSError` is raised if more than 40 symlinks are encountered while + resolving a path; this is taken to indicate a loop. + + .. method:: is_junction() + + Returns ``True`` if the path points to a junction. + + The default implementation of this method returns ``False`` rather than + raising :exc:`UnsupportedOperation`, because junctions are almost never + available in virtual filesystems. + + .. versionadded:: 3.13 + + Correspondence to tools in the :mod:`os` module ----------------------------------------------- diff --git a/Doc/whatsnew/3.13.rst b/Doc/whatsnew/3.13.rst index 785deea1c1e48f..b7c74d4880ac13 100644 --- a/Doc/whatsnew/3.13.rst +++ b/Doc/whatsnew/3.13.rst @@ -180,6 +180,12 @@ os pathlib ------- +* Add :class:`pathlib.PurePathBase` and :class:`~pathlib.PathBase` abstract + base classes. Users can subclass :class:`~pathlib.PathBase` to implement + *virtual paths*: objects representing paths in archive files, on remote + storage systems, and so forth. + (Contributed by Barney Gale in :gh:`110109`.) + * Add :exc:`pathlib.UnsupportedOperation`, which is raised instead of :exc:`NotImplementedError` when a path operation isn't supported. (Contributed by Barney Gale in :gh:`89812`.) diff --git a/Misc/NEWS.d/next/Library/2023-10-04-00-20-00.gh-issue-110109.RAaIgG.rst b/Misc/NEWS.d/next/Library/2023-10-04-00-20-00.gh-issue-110109.RAaIgG.rst new file mode 100644 index 00000000000000..32a027a4bcadbd --- /dev/null +++ b/Misc/NEWS.d/next/Library/2023-10-04-00-20-00.gh-issue-110109.RAaIgG.rst @@ -0,0 +1,4 @@ +Add :class:`pathlib.PurePathBase` and :class:`~pathlib.PathBase` abstract +base classes. Users can subclass :class:`pathlib.PathBase` to implement +*virtual paths*: objects that represent paths in archive files, remote +storage systems, disc images, etc.