mirror of
https://github.com/python/cpython.git
synced 2025-10-31 13:41:24 +00:00
99945c6b5c
* Separate out files relating to importlib.resources * Update Introduction to direct readers to the submodule documentation. * Create separate file for abcs relating to resources. * Move abc docs back to where they were.
385 lines
13 KiB
ReStructuredText
385 lines
13 KiB
ReStructuredText
.. 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 in a e.g. 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
|
|
|
|
.. abstractmethod:: open_resource(resource)
|
|
|
|
Returns an opened, :term:`file-like object` for binary reading
|
|
of the *resource*.
|
|
|
|
If the resource cannot be found, :exc:`FileNotFoundError` is
|
|
raised.
|
|
|
|
.. abstractmethod:: resource_path(resource)
|
|
|
|
Returns the file system path to the *resource*.
|
|
|
|
If the resource does not concretely exist on the file system,
|
|
raise :exc:`FileNotFoundError`.
|
|
|
|
.. abstractmethod:: is_resource(name)
|
|
|
|
Returns ``True`` if the named *name* is considered a resource.
|
|
:exc:`FileNotFoundError` is raised if *name* does not exist.
|
|
|
|
.. abstractmethod:: contents()
|
|
|
|
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:: ResourceLoader
|
|
|
|
An abstract base class for a :term:`loader` which implements the optional
|
|
:pep:`302` protocol for loading arbitrary resources from the storage
|
|
back-end.
|
|
|
|
.. deprecated:: 3.7
|
|
This ABC is deprecated in favour of supporting resource loading
|
|
through :class:`importlib.abc.ResourceReader`.
|
|
|
|
.. abstractmethod:: get_data(path)
|
|
|
|
An abstract method to return the bytes for the data located at *path*.
|
|
Loaders that have a file-like storage back-end
|
|
that allows storing arbitrary data
|
|
can implement this abstract method to give direct access
|
|
to the data stored. :exc:`OSError` is to be raised if the *path* cannot
|
|
be found. The *path* is expected to be constructed using a module's
|
|
:attr:`__file__` attribute or an item from a package's :attr:`__path__`.
|
|
|
|
.. versionchanged:: 3.4
|
|
Raises :exc:`OSError` instead of :exc:`NotImplementedError`.
|
|
|
|
|
|
.. class:: InspectLoader
|
|
|
|
An abstract base class for a :term:`loader` which implements the optional
|
|
:pep:`302` protocol for loaders that inspect modules.
|
|
|
|
.. method:: get_code(fullname)
|
|
|
|
Return the code object for a module, or ``None`` if the module does not
|
|
have a code object (as would be the case, for example, for a built-in
|
|
module). Raise an :exc:`ImportError` if loader cannot find the
|
|
requested module.
|
|
|
|
.. note::
|
|
While the method has a default implementation, it is suggested that
|
|
it be overridden if possible for performance.
|
|
|
|
.. index::
|
|
single: universal newlines; importlib.abc.InspectLoader.get_source method
|
|
|
|
.. versionchanged:: 3.4
|
|
No longer abstract and a concrete implementation is provided.
|
|
|
|
.. abstractmethod:: get_source(fullname)
|
|
|
|
An abstract method to return the source of a module. It is returned as
|
|
a text string using :term:`universal newlines`, translating all
|
|
recognized line separators into ``'\n'`` characters. Returns ``None``
|
|
if no source is available (e.g. a built-in module). Raises
|
|
:exc:`ImportError` if the loader cannot find the module specified.
|
|
|
|
.. versionchanged:: 3.4
|
|
Raises :exc:`ImportError` instead of :exc:`NotImplementedError`.
|
|
|
|
.. method:: is_package(fullname)
|
|
|
|
An optional method to return a true value if the module is a package, a
|
|
false value otherwise. :exc:`ImportError` is raised if the
|
|
:term:`loader` cannot find the module.
|
|
|
|
.. versionchanged:: 3.4
|
|
Raises :exc:`ImportError` instead of :exc:`NotImplementedError`.
|
|
|
|
.. staticmethod:: source_to_code(data, path='<string>')
|
|
|
|
Create a code object from Python source.
|
|
|
|
The *data* argument can be whatever the :func:`compile` function
|
|
supports (i.e. string or bytes). The *path* argument should be
|
|
the "path" to where the source code originated from, which can be an
|
|
abstract concept (e.g. location in a zip file).
|
|
|
|
With the subsequent code object one can execute it in a module by
|
|
running ``exec(code, module.__dict__)``.
|
|
|
|
.. versionadded:: 3.4
|
|
|
|
.. versionchanged:: 3.5
|
|
Made the method static.
|
|
|
|
.. method:: exec_module(module)
|
|
|
|
Implementation of :meth:`Loader.exec_module`.
|
|
|
|
.. versionadded:: 3.4
|
|
|
|
.. method:: load_module(fullname)
|
|
|
|
Implementation of :meth:`Loader.load_module`.
|
|
|
|
.. deprecated:: 3.4
|
|
use :meth:`exec_module` instead.
|
|
|
|
|
|
.. class:: ExecutionLoader
|
|
|
|
An abstract base class which inherits from :class:`InspectLoader` that,
|
|
when implemented, helps a module to be executed as a script. The ABC
|
|
represents an optional :pep:`302` protocol.
|
|
|
|
.. abstractmethod:: get_filename(fullname)
|
|
|
|
An abstract method that is to return the value of :attr:`__file__` for
|
|
the specified module. If no path is available, :exc:`ImportError` is
|
|
raised.
|
|
|
|
If source code is available, then the method should return the path to
|
|
the source file, regardless of whether a bytecode was used to load the
|
|
module.
|
|
|
|
.. versionchanged:: 3.4
|
|
Raises :exc:`ImportError` instead of :exc:`NotImplementedError`.
|
|
|
|
|
|
.. class:: FileLoader(fullname, path)
|
|
|
|
An abstract base class which inherits from :class:`ResourceLoader` and
|
|
:class:`ExecutionLoader`, providing concrete implementations of
|
|
:meth:`ResourceLoader.get_data` and :meth:`ExecutionLoader.get_filename`.
|
|
|
|
The *fullname* argument is a fully resolved name of the module the loader is
|
|
to handle. The *path* argument is the path to the file for the module.
|
|
|
|
.. versionadded:: 3.3
|
|
|
|
.. attribute:: name
|
|
|
|
The name of the module the loader can handle.
|
|
|
|
.. attribute:: path
|
|
|
|
Path to the file of the module.
|
|
|
|
.. method:: load_module(fullname)
|
|
|
|
Calls super's ``load_module()``.
|
|
|
|
.. deprecated:: 3.4
|
|
Use :meth:`Loader.exec_module` instead.
|
|
|
|
.. abstractmethod:: get_filename(fullname)
|
|
|
|
Returns :attr:`path`.
|
|
|
|
.. abstractmethod:: get_data(path)
|
|
|
|
Reads *path* as a binary file and returns the bytes from it.
|
|
|
|
|
|
.. class:: SourceLoader
|
|
|
|
An abstract base class for implementing source (and optionally bytecode)
|
|
file loading. The class inherits from both :class:`ResourceLoader` and
|
|
:class:`ExecutionLoader`, requiring the implementation of:
|
|
|
|
* :meth:`ResourceLoader.get_data`
|
|
* :meth:`ExecutionLoader.get_filename`
|
|
Should only return the path to the source file; sourceless
|
|
loading is not supported.
|
|
|
|
The abstract methods defined by this class are to add optional bytecode
|
|
file support. Not implementing these optional methods (or causing them to
|
|
raise :exc:`NotImplementedError`) causes the loader to
|
|
only work with source code. Implementing the methods allows the loader to
|
|
work with source *and* bytecode files; it does not allow for *sourceless*
|
|
loading where only bytecode is provided. Bytecode files are an
|
|
optimization to speed up loading by removing the parsing step of Python's
|
|
compiler, and so no bytecode-specific API is exposed.
|
|
|
|
.. method:: path_stats(path)
|
|
|
|
Optional abstract method which returns a :class:`dict` containing
|
|
metadata about the specified path. Supported dictionary keys are:
|
|
|
|
- ``'mtime'`` (mandatory): an integer or floating-point number
|
|
representing the modification time of the source code;
|
|
- ``'size'`` (optional): the size in bytes of the source code.
|
|
|
|
Any other keys in the dictionary are ignored, to allow for future
|
|
extensions. If the path cannot be handled, :exc:`OSError` is raised.
|
|
|
|
.. versionadded:: 3.3
|
|
|
|
.. versionchanged:: 3.4
|
|
Raise :exc:`OSError` instead of :exc:`NotImplementedError`.
|
|
|
|
.. method:: path_mtime(path)
|
|
|
|
Optional abstract method which returns the modification time for the
|
|
specified path.
|
|
|
|
.. deprecated:: 3.3
|
|
This method is deprecated in favour of :meth:`path_stats`. You don't
|
|
have to implement it, but it is still available for compatibility
|
|
purposes. Raise :exc:`OSError` if the path cannot be handled.
|
|
|
|
.. versionchanged:: 3.4
|
|
Raise :exc:`OSError` instead of :exc:`NotImplementedError`.
|
|
|
|
.. method:: set_data(path, data)
|
|
|
|
Optional abstract method which writes the specified bytes to a file
|
|
path. Any intermediate directories which do not exist are to be created
|
|
automatically.
|
|
|
|
When writing to the path fails because the path is read-only
|
|
(:attr:`errno.EACCES`/:exc:`PermissionError`), do not propagate the
|
|
exception.
|
|
|
|
.. versionchanged:: 3.4
|
|
No longer raises :exc:`NotImplementedError` when called.
|
|
|
|
.. method:: get_code(fullname)
|
|
|
|
Concrete implementation of :meth:`InspectLoader.get_code`.
|
|
|
|
.. method:: exec_module(module)
|
|
|
|
Concrete implementation of :meth:`Loader.exec_module`.
|
|
|
|
.. versionadded:: 3.4
|
|
|
|
.. method:: load_module(fullname)
|
|
|
|
Concrete implementation of :meth:`Loader.load_module`.
|
|
|
|
.. deprecated:: 3.4
|
|
Use :meth:`exec_module` instead.
|
|
|
|
.. method:: get_source(fullname)
|
|
|
|
Concrete implementation of :meth:`InspectLoader.get_source`.
|
|
|
|
.. method:: is_package(fullname)
|
|
|
|
Concrete implementation of :meth:`InspectLoader.is_package`. A module
|
|
is determined to be a package if its file path (as provided by
|
|
:meth:`ExecutionLoader.get_filename`) is a file named
|
|
``__init__`` when the file extension is removed **and** the module name
|
|
itself does not end in ``__init__``.
|
|
|
|
|
|
.. class:: Traversable
|
|
|
|
An object with a subset of pathlib.Path methods suitable for
|
|
traversing directories and opening files.
|
|
|
|
.. versionadded:: 3.9
|
|
|
|
.. attribute:: name
|
|
|
|
Abstract. The base name of this object without any parent references.
|
|
|
|
.. abstractmethod:: iterdir()
|
|
|
|
Yield Traversable objects in self.
|
|
|
|
.. abstractmethod:: is_dir()
|
|
|
|
Return True if self is a directory.
|
|
|
|
.. abstractmethod:: is_file()
|
|
|
|
Return True if self is a file.
|
|
|
|
.. abstractmethod:: joinpath(child)
|
|
|
|
Return Traversable child in self.
|
|
|
|
.. abstractmethod:: __truediv__(child)
|
|
|
|
Return Traversable child in self.
|
|
|
|
.. abstractmethod:: open(mode='r', *args, **kwargs)
|
|
|
|
*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 :attr:`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.abc.ResourceReader` and provides
|
|
concrete implementations of the :class:`importlib.abc.ResourceReader`'s
|
|
abstract methods. Therefore, any loader supplying
|
|
:class:`importlib.abc.TraversableReader` also supplies ResourceReader.
|
|
|
|
Loaders that wish to support resource reading are expected to
|
|
implement this interface.
|
|
|
|
.. versionadded:: 3.9
|
|
|
|
.. abstractmethod:: files()
|
|
|
|
Returns a :class:`importlib.abc.Traversable` object for the loaded
|
|
package.
|