traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Clarify some documentation

This commit is contained in:
Brett Cannon 2013-05-28 17:50:14 -04:00
parent f5fe13099e
commit a22faca714
1 changed files with 17 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
Doc/library/importlib.rst
View File

@ -800,7 +800,7 @@ an :term:`importer`.
.. decorator:: module_for_loader
A :term:`decorator` for a :term:`loader` method,
A :term:`decorator` for :meth:`importlib.abc.Loader.load_module`
to handle selecting the proper
module object to load with. The decorated method is expected to have a call
signature taking two positional arguments
@ -813,20 +813,16 @@ an :term:`importer`.
as expected for a :term:`loader`. If the module is not found in
:data:`sys.modules` then a new one is constructed with its
:attr:`__name__` attribute set to **name**, :attr:`__loader__` set to
**self**, and :attr:`__package__` set if
:meth:`importlib.abc.InspectLoader.is_package` is defined for **self** and
does not raise :exc:`ImportError` for **name**. If a new module is not
needed then the module found in :data:`sys.modules` will be passed into the
method.
**self**, and :attr:`__package__` set based on what
:meth:`importlib.abc.InspectLoader.is_package` returns (if available). If a
new module is not needed then the module found in :data:`sys.modules` will
be passed into the method.
If an exception is raised by the decorated method and a module was added to
:data:`sys.modules` it will be removed to prevent a partially initialized
module from being in left in :data:`sys.modules`. If the module was already
in :data:`sys.modules` then it is left alone.
Use of this decorator handles all the details of which module object a
loader should initialize as specified by :pep:`302` as best as possible.
.. note::
:class:`ModuleManager` subsumes the module management aspect of this
decorator.
@ -837,16 +833,16 @@ an :term:`importer`.
.. decorator:: set_loader
A :term:`decorator` for a :term:`loader` method,
A :term:`decorator` for :meth:`importlib.abc.Loader.load_module`
to set the :attr:`__loader__`
attribute on loaded modules. If the attribute is already set the decorator
does nothing. It is assumed that the first positional argument to the
wrapped method (i.e. ``self``) is what :attr:`__loader__` should be set to.
attribute on the returned module. If the attribute is already set the
decorator does nothing. It is assumed that the first positional argument to
the wrapped method (i.e. ``self``) is what :attr:`__loader__` should be set
to.
.. note::
It is recommended that :func:`module_for_loader` be used over this
decorator as it subsumes this functionality.
As this decorator sets :attr:`__loader__` after loading the module, it is
recommended to use :func:`module_for_loader` instead when appropriate.
.. versionchanged:: 3.4
Set ``__loader__`` if set to ``None``, as if the attribute does not
@ -855,19 +851,9 @@ an :term:`importer`.
.. decorator:: set_package
A :term:`decorator` for a :term:`loader` to set the :attr:`__package__`
attribute on the module returned by the loader. If :attr:`__package__` is
set and has a value other than ``None`` it will not be changed.
Note that the module returned by the loader is what has the attribute
set on and not the module found in :data:`sys.modules`.
Reliance on this decorator is discouraged when it is possible to set
:attr:`__package__` before importing. By
setting it beforehand the code for the module is executed with the
attribute set and thus can be used by global level code during
initialization.
A :term:`decorator` for :meth:`importlib.abc.Loader.load_module` to set the :attr:`__package__` attribute on the returned module. If :attr:`__package__`
is set and has a value other than ``None`` it will not be changed.
.. note::
It is recommended that :func:`module_for_loader` be used over this
decorator as it subsumes this functionality.
As this decorator sets :attr:`__package__` after loading the module, it is
recommended to use :func:`module_for_loader` instead when appropriate.