Implement the more specific PEP 302 semantics for loaders and what happens upon

load failure in relation to reloads. Also expose
importlib.util.module_for_loader to handle all of the details of this along
with making sure all current loaders behave nicely.

1 files changed, 33 insertions, 0 deletions

diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst
index 1a33fd4..dc015c7 100644
--- a/Doc/library/importlib.rst
+++ b/Doc/library/importlib.rst
@@ -151,3 +151,36 @@ find and load modules.
         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.
+
+
+:mod:`importlib.util` -- Utility code for importers
+---------------------------------------------------
+
+.. module:: importlib.util
+    :synopsis: Importers and path hooks
+
+This module contains the various objects that help in the construction of
+an :term:`importer`.
+
+.. function:: module_for_loader(method)
+
+    A :term:`decorator` for a :term:`loader` which handles selecting the proper
+    module object to load with. The decorated method is expected to have a call
+    signature of ``method(self, module_object)`` for which the second argument
+    will be the module object to be used (note that the decorator will not work
+    on static methods because of the assumption of two arguments).
+
+    The decorated method will take in the name of the module to be loaded as
+    normal. If the module is not found in :data:`sys.modules` then a new one is
+    constructed with its :attr:`__name__` attribute set. Otherwise 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 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 what module a loader
+    should use as specified by :pep:`302`.