mirror of
https://github.com/python/cpython.git
synced 2026-05-06 04:37:33 -04:00
gh-143513: Remove importlib.abc documentation for removed ABCs (#143605)
In 3.11 ResourceReader, Traversable, & TraversableResources moved from importlib.abc to importlib.resources.abc (commite712a5b277). In 3.12 old import locations were deprecated (commit71848c9609). In 3.14 backwards-compat support was removed (commit0751511d24). Co-authored-by: Brett Cannon <brett@python.org>
This commit is contained in:
Alex Willmer
@@ -596,172 +596,6 @@ ABC hierarchy::
|
||||
itself does not end in ``__init__``.
|
||||
|
||||
|
||||
.. class:: ResourceReader
|
||||
|
||||
*Superseded by TraversableResources*
|
||||
|
||||
An :term:`abstract base class` to provide the ability to read
|
||||
*resources*.
|
||||
|
||||
From the perspective of this ABC, a *resource* is a binary
|
||||
artifact that is shipped within a package. Typically this is
|
||||
something like a data file that lives next to the ``__init__.py``
|
||||
file of the package. The purpose of this class is to help abstract
|
||||
out the accessing of such data files so that it does not matter if
|
||||
the package and its data file(s) are stored e.g. in a zip file
|
||||
versus on the file system.
|
||||
|
||||
For any of methods of this class, a *resource* argument is
|
||||
expected to be a :term:`path-like object` which represents
|
||||
conceptually just a file name. This means that no subdirectory
|
||||
paths should be included in the *resource* argument. This is
|
||||
because the location of the package the reader is for, acts as the
|
||||
"directory". Hence the metaphor for directories and file
|
||||
names is packages and resources, respectively. This is also why
|
||||
instances of this class are expected to directly correlate to
|
||||
a specific package (instead of potentially representing multiple
|
||||
packages or a module).
|
||||
|
||||
Loaders that wish to support resource reading are expected to
|
||||
provide a method called ``get_resource_reader(fullname)`` which
|
||||
returns an object implementing this ABC's interface. If the module
|
||||
specified by fullname is not a package, this method should return
|
||||
:const:`None`. An object compatible with this ABC should only be
|
||||
returned when the specified module is a package.
|
||||
|
||||
.. versionadded:: 3.7
|
||||
|
||||
.. deprecated-removed:: 3.12 3.14
|
||||
Use :class:`importlib.resources.abc.TraversableResources` instead.
|
||||
|
||||
.. method:: open_resource(resource)
|
||||
:abstractmethod:
|
||||
|
||||
Returns an opened, :term:`file-like object` for binary reading
|
||||
of the *resource*.
|
||||
|
||||
If the resource cannot be found, :exc:`FileNotFoundError` is
|
||||
raised.
|
||||
|
||||
.. method:: resource_path(resource)
|
||||
:abstractmethod:
|
||||
|
||||
Returns the file system path to the *resource*.
|
||||
|
||||
If the resource does not concretely exist on the file system,
|
||||
raise :exc:`FileNotFoundError`.
|
||||
|
||||
.. method:: is_resource(name)
|
||||
:abstractmethod:
|
||||
|
||||
Returns ``True`` if the named *name* is considered a resource.
|
||||
:exc:`FileNotFoundError` is raised if *name* does not exist.
|
||||
|
||||
.. method:: contents()
|
||||
:abstractmethod:
|
||||
|
||||
Returns an :term:`iterable` of strings over the contents of
|
||||
the package. Do note that it is not required that all names
|
||||
returned by the iterator be actual resources, e.g. it is
|
||||
acceptable to return names for which :meth:`is_resource` would
|
||||
be false.
|
||||
|
||||
Allowing non-resource names to be returned is to allow for
|
||||
situations where how a package and its resources are stored
|
||||
are known a priori and the non-resource names would be useful.
|
||||
For instance, returning subdirectory names is allowed so that
|
||||
when it is known that the package and resources are stored on
|
||||
the file system then those subdirectory names can be used
|
||||
directly.
|
||||
|
||||
The abstract method returns an iterable of no items.
|
||||
|
||||
|
||||
.. class:: Traversable
|
||||
|
||||
An object with a subset of :class:`pathlib.Path` methods suitable for
|
||||
traversing directories and opening files.
|
||||
|
||||
For a representation of the object on the file-system, use
|
||||
:meth:`importlib.resources.as_file`.
|
||||
|
||||
.. versionadded:: 3.9
|
||||
|
||||
.. deprecated-removed:: 3.12 3.14
|
||||
Use :class:`importlib.resources.abc.Traversable` instead.
|
||||
|
||||
.. attribute:: name
|
||||
|
||||
Abstract. The base name of this object without any parent references.
|
||||
|
||||
.. method:: iterdir()
|
||||
:abstractmethod:
|
||||
|
||||
Yield ``Traversable`` objects in ``self``.
|
||||
|
||||
.. method:: is_dir()
|
||||
:abstractmethod:
|
||||
|
||||
Return ``True`` if ``self`` is a directory.
|
||||
|
||||
.. method:: is_file()
|
||||
:abstractmethod:
|
||||
|
||||
Return ``True`` if ``self`` is a file.
|
||||
|
||||
.. method:: joinpath(child)
|
||||
:abstractmethod:
|
||||
|
||||
Return Traversable child in ``self``.
|
||||
|
||||
.. method:: __truediv__(child)
|
||||
:abstractmethod:
|
||||
|
||||
Return ``Traversable`` child in ``self``.
|
||||
|
||||
.. method:: open(mode='r', *args, **kwargs)
|
||||
:abstractmethod:
|
||||
|
||||
*mode* may be 'r' or 'rb' to open as text or binary. Return a handle
|
||||
suitable for reading (same as :attr:`pathlib.Path.open`).
|
||||
|
||||
When opening as text, accepts encoding parameters such as those
|
||||
accepted by :class:`io.TextIOWrapper`.
|
||||
|
||||
.. method:: read_bytes()
|
||||
|
||||
Read contents of ``self`` as bytes.
|
||||
|
||||
.. method:: read_text(encoding=None)
|
||||
|
||||
Read contents of ``self`` as text.
|
||||
|
||||
|
||||
.. class:: TraversableResources
|
||||
|
||||
An abstract base class for resource readers capable of serving
|
||||
the :meth:`importlib.resources.files` interface. Subclasses
|
||||
:class:`importlib.resources.abc.ResourceReader` and provides
|
||||
concrete implementations of the :class:`importlib.resources.abc.ResourceReader`'s
|
||||
abstract methods. Therefore, any loader supplying
|
||||
:class:`importlib.abc.TraversableResources` also supplies ResourceReader.
|
||||
|
||||
Loaders that wish to support resource reading are expected to
|
||||
implement this interface.
|
||||
|
||||
.. versionadded:: 3.9
|
||||
|
||||
.. deprecated-removed:: 3.12 3.14
|
||||
Use :class:`importlib.resources.abc.TraversableResources` instead.
|
||||
|
||||
.. method:: files()
|
||||
:abstractmethod:
|
||||
|
||||
Returns a :class:`importlib.resources.abc.Traversable` object for the loaded
|
||||
package.
|
||||
|
||||
|
||||
|
||||
:mod:`importlib.machinery` -- Importers and path hooks
|
||||
------------------------------------------------------
|
||||
|
||||
|
||||
@@ -604,7 +604,7 @@ new ABC for access to, opening, and reading *resources* inside packages.
|
||||
Resources are roughly similar to files inside packages, but they needn't
|
||||
be actual files on the physical file system. Module loaders can provide a
|
||||
:meth:`!get_resource_reader` function which returns
|
||||
a :class:`importlib.abc.ResourceReader` instance to support this
|
||||
a :class:`!importlib.abc.ResourceReader` instance to support this
|
||||
new API. Built-in file path loaders and zip file loaders both support this.
|
||||
|
||||
Contributed by Barry Warsaw and Brett Cannon in :issue:`32248`.
|
||||
@@ -1043,7 +1043,7 @@ window are shown and hidden in the Options menu.
|
||||
importlib
|
||||
---------
|
||||
|
||||
The :class:`importlib.abc.ResourceReader` ABC was introduced to
|
||||
The :class:`!importlib.abc.ResourceReader` ABC was introduced to
|
||||
support the loading of resources from packages. See also
|
||||
:ref:`whatsnew37_importlib_resources`.
|
||||
(Contributed by Barry Warsaw, Brett Cannon in :issue:`32248`.)
|
||||
@@ -2032,7 +2032,7 @@ both deprecated in Python 3.4 now emit :exc:`DeprecationWarning`.
|
||||
(Contributed by Matthias Bussonnier in :issue:`29576`.)
|
||||
|
||||
The :class:`importlib.abc.ResourceLoader` ABC has been deprecated in
|
||||
favour of :class:`importlib.abc.ResourceReader`.
|
||||
favour of :class:`!importlib.abc.ResourceReader`.
|
||||
|
||||
|
||||
locale
|
||||
|
||||
@@ -403,7 +403,7 @@ SOCK_CLOEXEC.
|
||||
.. nonce: zmO8G2
|
||||
.. section: Library
|
||||
|
||||
Add :class:`importlib.abc.ResourceReader` as an ABC for loaders to provide a
|
||||
Add :class:`!importlib.abc.ResourceReader` as an ABC for loaders to provide a
|
||||
unified API for reading resources contained within packages. Also add
|
||||
:mod:`importlib.resources` as the port of ``importlib_resources``.
|
||||
|
||||
|
||||
@@ -598,7 +598,7 @@ Add socket.getblocking() method.
|
||||
.. nonce: zmO8G2
|
||||
.. section: Library
|
||||
|
||||
Add :mod:`importlib.resources` and :class:`importlib.abc.ResourceReader` as
|
||||
Add :mod:`importlib.resources` and :class:`!importlib.abc.ResourceReader` as
|
||||
the unified API for reading resources contained within packages. Loaders
|
||||
wishing to support resource reading must implement the
|
||||
:meth:`get_resource_reader` method. File-based and zipimport-based
|
||||
|
||||
@@ -152,7 +152,7 @@ Ensure line-endings are respected when using lib2to3.
|
||||
.. section: Library
|
||||
|
||||
Have :func:`importlib.resources.contents` and
|
||||
:meth:`importlib.abc.ResourceReader.contents` return an :term:`iterable`
|
||||
:meth:`!importlib.abc.ResourceReader.contents` return an :term:`iterable`
|
||||
instead of an :term:`iterator`.
|
||||
|
||||
..
|
||||
|
||||
@@ -5130,7 +5130,7 @@ Ensure line-endings are respected when using lib2to3.
|
||||
.. section: Library
|
||||
|
||||
Have :func:`importlib.resources.contents` and
|
||||
:meth:`importlib.abc.ResourceReader.contents` return an :term:`iterable`
|
||||
:meth:`!importlib.abc.ResourceReader.contents` return an :term:`iterable`
|
||||
instead of an :term:`iterator`.
|
||||
|
||||
..
|
||||
|
||||
Reference in New Issue
Block a user