mirror of
https://github.com/python/cpython.git
synced 2025-08-02 16:13:13 +00:00
bpo-37800: Clean up importlib documentation for some module attributes (GH-10016)
Automerge-Triggered-By: GH:brettcannon
This commit is contained in:
Géry Ogam
GitHub
parent
df4ae55e66
commit
d7e210070f
1 changed files with 77 additions and 63 deletions
|
|
@ -383,11 +383,11 @@ ABC hierarchy::
|
|||
See :pep:`302` for the exact definition for a loader.
|
||||
|
||||
Loaders that wish to support resource reading should implement a
|
||||
``get_resource_reader(fullname)`` method as specified by
|
||||
:meth:`get_resource_reader` method as specified by
|
||||
:class:`importlib.abc.ResourceReader`.
|
||||
|
||||
.. versionchanged:: 3.7
|
||||
Introduced the optional ``get_resource_reader()`` method.
|
||||
Introduced the optional :meth:`get_resource_reader` method.
|
||||
|
||||
.. method:: create_module(spec)
|
||||
|
||||
|
|
@ -405,17 +405,17 @@ ABC hierarchy::
|
|||
|
||||
An abstract method that executes the module in its own namespace
|
||||
when a module is imported or reloaded. The module should already
|
||||
be initialized when ``exec_module()`` is called. When this method exists,
|
||||
:meth:`~importlib.abc.Loader.create_module` must be defined.
|
||||
be initialized when :meth:`exec_module` is called. When this method exists,
|
||||
:meth:`create_module` must be defined.
|
||||
|
||||
.. versionadded:: 3.4
|
||||
|
||||
.. versionchanged:: 3.6
|
||||
:meth:`~importlib.abc.Loader.create_module` must also be defined.
|
||||
:meth:`create_module` must also be defined.
|
||||
|
||||
.. method:: load_module(fullname)
|
||||
|
||||
A legacy method for loading a module. If the module cannot be
|
||||
A legacy method for loading a module. If the module cannot be
|
||||
loaded, :exc:`ImportError` is raised, otherwise the loaded module is
|
||||
returned.
|
||||
|
||||
|
|
@ -423,62 +423,64 @@ ABC hierarchy::
|
|||
module should be used and reloaded.
|
||||
Otherwise the loader should create a new module and insert it into
|
||||
:data:`sys.modules` before any loading begins, to prevent recursion
|
||||
from the import. If the loader inserted a module and the load fails, it
|
||||
from the import. If the loader inserted a module and the load fails, it
|
||||
must be removed by the loader from :data:`sys.modules`; modules already
|
||||
in :data:`sys.modules` before the loader began execution should be left
|
||||
alone (see :func:`importlib.util.module_for_loader`).
|
||||
|
||||
The loader should set several attributes on the module.
|
||||
(Note that some of these attributes can change when a module is
|
||||
The loader should set several attributes on the module
|
||||
(note that some of these attributes can change when a module is
|
||||
reloaded):
|
||||
|
||||
- :attr:`__name__`
|
||||
The name of the module.
|
||||
The module's fully-qualified name.
|
||||
It is ``'__main__'`` for an executed module.
|
||||
|
||||
- :attr:`__file__`
|
||||
The path to where the module data is stored (not set for built-in
|
||||
modules).
|
||||
The location the :term:`loader` used to load the module.
|
||||
For example, for modules loaded from a .py file this is the filename.
|
||||
It is not set on all modules (e.g. built-in modules).
|
||||
|
||||
- :attr:`__cached__`
|
||||
The path to where a compiled version of the module is/should be
|
||||
stored (not set when the attribute would be inappropriate).
|
||||
The filename of a compiled version of the module's code.
|
||||
It is not set on all modules (e.g. built-in modules).
|
||||
|
||||
- :attr:`__path__`
|
||||
A list of strings specifying the search path within a
|
||||
package. This attribute is not set on modules.
|
||||
The list of locations where the package's submodules will be found.
|
||||
Most of the time this is a single directory.
|
||||
The import system passes this attribute to ``__import__()`` and to finders
|
||||
in the same way as :attr:`sys.path` but just for the package.
|
||||
It is not set on non-package modules so it can be used
|
||||
as an indicator that the module is a package.
|
||||
|
||||
- :attr:`__package__`
|
||||
The fully-qualified name of the package under which the module was
|
||||
loaded as a submodule (or the empty string for top-level modules).
|
||||
For packages, it is the same as :attr:`__name__`. The
|
||||
:func:`importlib.util.module_for_loader` decorator can handle the
|
||||
details for :attr:`__package__`.
|
||||
The fully-qualified name of the package the module is in (or the
|
||||
empty string for a top-level module).
|
||||
If the module is a package then this is the same as :attr:`__name__`.
|
||||
|
||||
- :attr:`__loader__`
|
||||
The loader used to load the module. The
|
||||
:func:`importlib.util.module_for_loader` decorator can handle the
|
||||
details for :attr:`__package__`.
|
||||
The :term:`loader` used to load the module.
|
||||
|
||||
When :meth:`exec_module` is available then backwards-compatible
|
||||
functionality is provided.
|
||||
|
||||
.. versionchanged:: 3.4
|
||||
Raise :exc:`ImportError` when called instead of
|
||||
:exc:`NotImplementedError`. Functionality provided when
|
||||
:exc:`NotImplementedError`. Functionality provided when
|
||||
:meth:`exec_module` is available.
|
||||
|
||||
.. deprecated:: 3.4
|
||||
The recommended API for loading a module is :meth:`exec_module`
|
||||
(and :meth:`create_module`). Loaders should implement
|
||||
it instead of load_module(). The import machinery takes care of
|
||||
all the other responsibilities of load_module() when exec_module()
|
||||
is implemented.
|
||||
(and :meth:`create_module`). Loaders should implement it instead of
|
||||
:meth:`load_module`. The import machinery takes care of all the
|
||||
other responsibilities of :meth:`load_module` when
|
||||
:meth:`exec_module` is implemented.
|
||||
|
||||
.. method:: module_repr(module)
|
||||
|
||||
A legacy method which when implemented calculates and returns the
|
||||
given module's repr, as a string. The module type's default repr() will
|
||||
use the result of this method as appropriate.
|
||||
A legacy method which when implemented calculates and returns the given
|
||||
module's representation, as a string. The module type's default
|
||||
:meth:`__repr__` will use the result of this method as appropriate.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
|
|
@ -1420,69 +1422,80 @@ find and load modules.
|
|||
.. class:: ModuleSpec(name, loader, *, origin=None, loader_state=None, is_package=None)
|
||||
|
||||
A specification for a module's import-system-related state. This is
|
||||
typically exposed as the module's ``__spec__`` attribute. In the
|
||||
typically exposed as the module's :attr:`__spec__` attribute. In the
|
||||
descriptions below, the names in parentheses give the corresponding
|
||||
attribute available directly on the module object.
|
||||
E.g. ``module.__spec__.origin == module.__file__``. Note however that
|
||||
attribute available directly on the module object,
|
||||
e.g. ``module.__spec__.origin == module.__file__``. Note, however, that
|
||||
while the *values* are usually equivalent, they can differ since there is
|
||||
no synchronization between the two objects. Thus it is possible to update
|
||||
the module's ``__path__`` at runtime, and this will not be automatically
|
||||
reflected in ``__spec__.submodule_search_locations``.
|
||||
no synchronization between the two objects. For example, it is possible to update
|
||||
the module's :attr:`__file__` at runtime and this will not be automatically
|
||||
reflected in the module's :attr:`__spec__.origin`, and vice versa.
|
||||
|
||||
.. versionadded:: 3.4
|
||||
|
||||
.. attribute:: name
|
||||
|
||||
(``__name__``)
|
||||
(:attr:`__name__`)
|
||||
|
||||
A string for the fully-qualified name of the module.
|
||||
The module's fully-qualified name.
|
||||
The :term:`finder` should always set this attribute to a non-empty string.
|
||||
|
||||
.. attribute:: loader
|
||||
|
||||
(``__loader__``)
|
||||
(:attr:`__loader__`)
|
||||
|
||||
The :term:`Loader <loader>` that should be used when loading
|
||||
the module. :term:`Finders <finder>` should always set this.
|
||||
The :term:`loader` used to load the module.
|
||||
The :term:`finder` should always set this attribute.
|
||||
|
||||
.. attribute:: origin
|
||||
|
||||
(``__file__``)
|
||||
(:attr:`__file__`)
|
||||
|
||||
Name of the place from which the module is loaded, e.g. "builtin" for
|
||||
built-in modules and the filename for modules loaded from source.
|
||||
Normally "origin" should be set, but it may be ``None`` (the default)
|
||||
which indicates it is unspecified (e.g. for namespace packages).
|
||||
The location the :term:`loader` should use to load the module.
|
||||
For example, for modules loaded from a .py file this is the filename.
|
||||
The :term:`finder` should always set this attribute to a meaningful value
|
||||
for the :term:`loader` to use. In the uncommon case that there is not one
|
||||
(like for namespace packages), it should be set to ``None``.
|
||||
|
||||
.. attribute:: submodule_search_locations
|
||||
|
||||
(``__path__``)
|
||||
(:attr:`__path__`)
|
||||
|
||||
List of strings for where to find submodules, if a package (``None``
|
||||
otherwise).
|
||||
The list of locations where the package's submodules will be found.
|
||||
Most of the time this is a single directory.
|
||||
The :term:`finder` should set this attribute to a list, even an empty one, to indicate
|
||||
to the import system that the module is a package. It should be set to ``None`` for
|
||||
non-package modules. It is set automatically later to a special object for
|
||||
namespace packages.
|
||||
|
||||
.. attribute:: loader_state
|
||||
|
||||
Container of extra module-specific data for use during loading (or
|
||||
``None``).
|
||||
The :term:`finder` may set this attribute to an object containing additional,
|
||||
module-specific data to use when loading the module. Otherwise it should be
|
||||
set to ``None``.
|
||||
|
||||
.. attribute:: cached
|
||||
|
||||
(``__cached__``)
|
||||
(:attr:`__cached__`)
|
||||
|
||||
String for where the compiled module should be stored (or ``None``).
|
||||
The filename of a compiled version of the module's code.
|
||||
The :term:`finder` should always set this attribute but it may be ``None``
|
||||
for modules that do not need compiled code stored.
|
||||
|
||||
.. attribute:: parent
|
||||
|
||||
(``__package__``)
|
||||
(:attr:`__package__`)
|
||||
|
||||
(Read-only) The fully-qualified name of the package under which the module
|
||||
should be loaded as a submodule (or the empty string for top-level modules).
|
||||
For packages, it is the same as :attr:`__name__`.
|
||||
(Read-only) The fully-qualified name of the package the module is in (or the
|
||||
empty string for a top-level module).
|
||||
If the module is a package then this is the same as :attr:`name`.
|
||||
|
||||
.. attribute:: has_location
|
||||
|
||||
Boolean indicating whether or not the module's "origin"
|
||||
attribute refers to a loadable location.
|
||||
``True`` if the spec's :attr:`origin` refers to a loadable location,
|
||||
``False`` otherwise. This value impacts how :attr:`origin` is interpreted
|
||||
and how the module's :attr:`__file__` is populated.
|
||||
|
||||
|
||||
:mod:`importlib.util` -- Utility code for importers
|
||||
---------------------------------------------------
|
||||
|
|
@ -1574,8 +1587,9 @@ an :term:`importer`.
|
|||
|
||||
:exc:`ImportError` is raised if **name** is a relative module name but
|
||||
**package** is a false value (e.g. ``None`` or the empty string).
|
||||
:exc:`ImportError` is also raised a relative name would escape its containing
|
||||
package (e.g. requesting ``..bacon`` from within the ``spam`` package).
|
||||
:exc:`ImportError` is also raised if a relative name would escape its
|
||||
containing package (e.g. requesting ``..bacon`` from within the ``spam``
|
||||
package).
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue