[Python-checkins] cpython: Issue #19713: Update importlib docs for module spec changes, including
eric.snow
python-checkins at python.org
Tue Dec 17 07:11:56 CET 2013
http://hg.python.org/cpython/rev/2c27c0e5bc50
changeset: 88016:2c27c0e5bc50
user: Eric Snow <ericsnowcurrently at gmail.com>
date: Mon Dec 16 23:06:52 2013 -0700
summary:
Issue #19713: Update importlib docs for module spec changes, including deprecations.
files:
Doc/glossary.rst | 4 +
Doc/library/importlib.rst | 172 ++++++++++++++++++++++---
2 files changed, 154 insertions(+), 22 deletions(-)
diff --git a/Doc/glossary.rst b/Doc/glossary.rst
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -539,6 +539,10 @@
See also :term:`package`.
+ module spec
+ A namespace containing the import-related information used to load a
+ module.
+
MRO
See :term:`method resolution order`.
diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst
--- a/Doc/library/importlib.rst
+++ b/Doc/library/importlib.rst
@@ -89,6 +89,22 @@
.. versionchanged:: 3.3
Parent packages are automatically imported.
+.. function:: find_spec(name, path=None)
+
+ Find the :term:`spec <module spec>` for a module, optionally within the
+ specified *path*. If the module is in :attr:`sys.modules`, then
+ ``sys.modules[name].__spec__`` is returned (unless the spec would be
+ ``None`` or is not set, in which case :exc:`ValueError` is raised).
+ Otherwise a search using :attr:`sys.meta_path` is done. ``None`` is
+ returned if no spec is found.
+
+ A dotted name does not have its parent implicitly imported as that requires
+ loading them and that may not be desired. To properly import a submodule you
+ will need to import all parent packages of the submodule and use the correct
+ argument to *path*.
+
+ .. versionadded:: 3.4
+
.. function:: find_loader(name, path=None)
Find the loader for a module, optionally within the specified *path*. If the
@@ -108,6 +124,9 @@
If ``__loader__`` is not set, raise :exc:`ValueError`, just like when the
attribute is set to ``None``.
+ .. deprecated:: 3.4
+ Use :func:`find_spec` instead.
+
.. function:: invalidate_caches()
Invalidate the internal caches of finders stored at
@@ -236,9 +255,21 @@
.. versionadded:: 3.3
+ .. method:: find_spec(fullname, path, target=None)
+
+ An abstract method for finding a :term:`spec <module spec>` for
+ the specified module. If this is a top-level import, *path* will
+ be ``None``. Otherwise, this is a search for a subpackage or
+ module and *path* will be the value of :attr:`__path__` from the
+ parent package. If a spec cannot be found, ``None`` is returned.
+ When passed in, ``target`` is a module object that the finder may
+ use to make a more educated about what spec to return.
+
+ .. versionadded:: 3.4
+
.. method:: find_module(fullname, path)
- An abstract method for finding a :term:`loader` for the specified
+ A legacy method for finding a :term:`loader` for the specified
module. If this is a top-level import, *path* will be ``None``.
Otherwise, this is a search for a subpackage or module and *path*
will be the value of :attr:`__path__` from the parent
@@ -248,6 +279,9 @@
Returns ``None`` when called instead of raising
:exc:`NotImplementedError`.
+ .. deprecated:: 3.4
+ Use :meth:`find_spec` instead.
+
.. method:: invalidate_caches()
An optional method which, when called, should invalidate any internal
@@ -268,9 +302,20 @@
.. versionadded:: 3.3
+ .. method:: find_spec(fullname, target=None)
+
+ An abstract method for finding a :term:`spec <module spec>` for
+ the specified module. The finder will search for the module only
+ within the :term:`path entry` to which it is assigned. If a spec
+ cannot be found, ``None`` is returned. When passed in, ``target``
+ is a module object that the finder may use to make a more educated
+ about what spec to return.
+
+ .. versionadded:: 3.4
+
.. method:: find_loader(fullname)
- An abstract method for finding a :term:`loader` for the specified
+ A legacy method for finding a :term:`loader` for the specified
module. Returns a 2-tuple of ``(loader, portion)`` where ``portion``
is a sequence of file system locations contributing to part of a namespace
package. The loader may be ``None`` while specifying ``portion`` to
@@ -283,11 +328,17 @@
.. versionchanged:: 3.4
Returns ``(None, [])`` instead of raising :exc:`NotImplementedError`.
+ .. deprecated:: 3.4
+ Use :meth:`find_spec` instead.
+
.. method:: find_module(fullname)
A concrete implementation of :meth:`Finder.find_module` which is
equivalent to ``self.find_loader(fullname)[0]``.
+ .. deprecated:: 3.4
+ Use :meth:`find_spec` instead.
+
.. method:: invalidate_caches()
An optional method which, when called, should invalidate any internal
@@ -300,9 +351,26 @@
An abstract base class for a :term:`loader`.
See :pep:`302` for the exact definition for a loader.
+ .. method:: create_module(spec)
+
+ An optional method that returns the module object to use when
+ importing a module. create_module() may also return ``None``,
+ indicating that the default module creation should take place
+ instead.
+
+ .. versionadded:: 3.4
+
+ .. method:: exec_module(module)
+
+ 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.
+
+ .. versionadded:: 3.4
+
.. method:: load_module(fullname)
- An abstract 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.
@@ -349,9 +417,16 @@
Raise :exc:`ImportError` when called instead of
:exc:`NotImplementedError`.
+ .. deprecated:: 3.4
+ The recommended API for loading a module is :meth:`exec_module`
+ (and optionally :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.
+
.. method:: module_repr(module)
- An optional method which when implemented calculates and returns the
+ 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.
@@ -360,6 +435,9 @@
.. versionchanged:: 3.4
Made optional instead of an abstractmethod.
+ .. deprecated:: 3.4
+ The import machinery now takes care of this automatically.
+
.. class:: ResourceLoader
@@ -434,9 +512,18 @@
.. versionadded:: 3.4
+ .. method:: exec_module(module)
+
+ Implementation of :meth:`Loader.exec_module`.
+
+ .. versionadded:: 3.4
+
.. method:: load_module(fullname)
- Implementation of :meth:`Loader.load_module`.
+ Implementation of :meth:`Loader.load_module`.
+
+ .. deprecated:: 3.4
+ use :meth:`exec_module` instead.
.. class:: ExecutionLoader
@@ -482,6 +569,9 @@
Calls super's ``load_module()``.
+ .. deprecated:: 3.4
+ Use :meth:`Loader.exec_module` instead.
+
.. method:: get_filename(fullname)
Returns :attr:`path`.
@@ -558,9 +648,18 @@
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`.
+ Concrete implementation of :meth:`Loader.load_module`.
+
+ .. deprecated:: 3.4
+ Use :meth:`exec_module` instead.
.. method:: get_source(fullname)
@@ -641,6 +740,10 @@
Only class methods are defined by this class to alleviate the need for
instantiation.
+ .. note::
+ Due to limitations in the extension module C-API, for now
+ BuiltinImporter does not implement :meth:`Loader.exec_module`.
+
.. class:: FrozenImporter
@@ -671,28 +774,37 @@
Only class methods are defined by this class to alleviate the need for
instantiation.
+ .. classmethod:: find_spec(fullname, path=None, target=None)
+
+ Class method that attempts to find a :term:`spec <module spec>`
+ for the module specified by *fullname* on :data:`sys.path` or, if
+ defined, on *path*. For each path entry that is searched,
+ :data:`sys.path_importer_cache` is checked. If a non-false object
+ is found then it is used as the :term:`path entry finder` to look
+ for the module being searched for. If no entry is found in
+ :data:`sys.path_importer_cache`, then :data:`sys.path_hooks` is
+ searched for a finder for the path entry and, if found, is stored
+ in :data:`sys.path_importer_cache` along with being queried about
+ the module. If no finder is ever found then ``None`` is both
+ stored in the cache and returned.
+
+ .. versionadded:: 3.4
+
.. classmethod:: find_module(fullname, path=None)
- Class method that attempts to find a :term:`loader` for the module
- specified by *fullname* on :data:`sys.path` or, if defined, on
- *path*. For each path entry that is searched,
- :data:`sys.path_importer_cache` is checked. If a non-false object is
- found then it is used as the :term:`path entry finder` to look for the
- module being searched for. If no entry is found in
- :data:`sys.path_importer_cache`, then :data:`sys.path_hooks` is
- searched for a finder for the path entry and, if found, is stored in
- :data:`sys.path_importer_cache` along with being queried about the
- module. If no finder is ever found then ``None`` is both stored in
- the cache and returned.
+ A legacy wrapper around :meth:`find_spec`.
+
+ .. deprecated:: 3.4
+ Use :meth:`find_spec` instead.
.. classmethod:: invalidate_caches()
- Calls :meth:`importlib.abc.PathEntryFinder.invalidate_caches` on all
- finders stored in :attr:`sys.path_importer_cache`.
+ Calls :meth:`importlib.abc.PathEntryFinder.invalidate_caches` on all
+ finders stored in :attr:`sys.path_importer_cache`.
- .. versionchanged:: 3.4
- Calls objects in :data:`sys.path_hooks` with the current working directory
- for ``''`` (i.e. the empty string).
+ .. versionchanged:: 3.4
+ Calls objects in :data:`sys.path_hooks` with the current working
+ directory for ``''`` (i.e. the empty string).
.. class:: FileFinder(path, \*loader_details)
@@ -724,6 +836,12 @@
The path the finder will search in.
+ .. method:: find_spec(fullname, target=None)
+
+ Attempt to find the spec to handle *fullname* within :attr:`path`.
+
+ .. versionadded:: 3.4
+
.. method:: find_loader(fullname)
Attempt to find the loader to handle *fullname* within :attr:`path`.
@@ -829,6 +947,10 @@
Loads the extension module if and only if *fullname* is the same as
:attr:`name` or is ``None``.
+ .. note::
+ Due to limitations in the extension module C-API, for now
+ ExtensionFileLoader does not implement :meth:`Loader.exec_module`.
+
.. method:: is_package(fullname)
Returns ``True`` if the file path points to a package's ``__init__``
@@ -1026,11 +1148,17 @@
Set ``__loader__`` if set to ``None``, as if the attribute does not
exist.
+ .. deprecated:: 3.4
+ The import machinery takes care of this automatically.
+
.. decorator:: set_package
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.
+ .. deprecated:: 3.4
+ The import machinery takes care of this automatically.
+
.. function:: spec_from_loader(name, loader, *, origin=None, is_package=None)
A factory function for creating a :class:`ModuleSpec` instance based
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list