diff options
| author | Brett Cannon <brett@python.org> | 2015-01-09 16:39:21 (GMT) |
|---|---|---|
| committer | Brett Cannon <brett@python.org> | 2015-01-09 16:39:21 (GMT) |
| commit | 02d845400275076ef5ba2791c74b7670ac21f8a9 (patch) | |
| tree | 36077086a1bd393ede07d99c61ed7137bd5bdcc3 /Doc/library/importlib.rst | |
| parent | 863c69cfebcafbf97ba401e0f3cd5cb077e0e8f2 (diff) | |
| download | cpython-02d845400275076ef5ba2791c74b7670ac21f8a9.zip cpython-02d845400275076ef5ba2791c74b7670ac21f8a9.tar.gz cpython-02d845400275076ef5ba2791c74b7670ac21f8a9.tar.bz2 | |
Issue #23014: Make importlib.abc.Loader.create_module() required when
importlib.abc.Loader.exec_module() is also defined.
Before this change, create_module() was optional **and** could return
None to trigger default semantics. This change now reduces the
options for choosing default semantics to one and in the most
backporting-friendly way (define create_module() to return None).
Diffstat (limited to 'Doc/library/importlib.rst')
| -rw-r--r-- | Doc/library/importlib.rst | 24 |
1 files changed, 14 insertions, 10 deletions
diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index 3af8d62..9c6b280 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -347,13 +347,16 @@ ABC hierarchy:: .. 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. + A method that returns the module object to use when + importing a module. This method may return ``None``, + indicating that default module creation semantics should take place. .. versionadded:: 3.4 + .. versionchanged:: 3.5 + Starting in Python 3.6, this method will not be optional when + :meth:`exec_module` is defined. + .. method:: exec_module(module) An abstract method that executes the module in its own namespace @@ -417,7 +420,7 @@ ABC hierarchy:: .. deprecated:: 3.4 The recommended API for loading a module is :meth:`exec_module` - (and optionally :meth:`create_module`). Loaders should implement + (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. @@ -1136,9 +1139,9 @@ an :term:`importer`. .. function:: module_from_spec(spec) - Create a new module based on **spec**. + Create a new module based on **spec** and ``spec.loader.create_module()``. - If the module object is from ``spec.loader.create_module()``, then any + If ``spec.loader.create_module()`` does not return ``None``, then any pre-existing attributes will not be reset. Also, no :exc:`AttributeError` will be raised if triggered while accessing **spec** or setting an attribute on the module. @@ -1234,9 +1237,10 @@ an :term:`importer`. module has an attribute accessed. This class **only** works with loaders that define - :meth:`importlib.abc.Loader.exec_module` as control over what module type - is used for the module is required. For the same reasons, the loader - **cannot** define :meth:`importlib.abc.Loader.create_module`. Finally, + :meth:`~importlib.abc.Loader.exec_module` as control over what module type + is used for the module is required. For those same reasons, the loader's + :meth:`~importlib.abc.Loader.create_module` method will be ignored (i.e., the + loader's method should only return ``None``). Finally, modules which substitute the object placed into :attr:`sys.modules` will not work as there is no way to properly replace the module references throughout the interpreter safely; :exc:`ValueError` is raised if such a |