Issue #14646: __import__() now sets __loader__ if need be.

importlib.util.module_for_loader also will set __loader__ along with
__package__. This is in conjunction to a forthcoming update to PEP 302
which will make these two attributes required for loaders to set.

1 files changed, 25 insertions, 7 deletions

diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst
index a8013d2..6855a79 100644
--- a/Doc/library/importlib.rst
+++ b/Doc/library/importlib.rst
@@ -697,22 +697,30 @@ an :term:`importer`.
     signature taking two positional arguments
     (e.g. ``load_module(self, module)``) for which the second argument
     will be the module **object** to be used by the loader.
-    Note that the decorator
-    will not work on static methods because of the assumption of two
-    arguments.
+    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 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. 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
+    :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.
+
+    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`.
+    loader should initialize as specified by :pep:`302` as best as possible.
+
+    .. versionchanged:: 3.3
+      :attr:`__loader__` and :attr:`__package__` are automatically set
+      (when possible).
 
 .. decorator:: set_loader
 
@@ -722,6 +730,12 @@ an :term:`importer`.
     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.
+
+
 .. decorator:: set_package
 
     A :term:`decorator` for a :term:`loader` to set the :attr:`__package__`
@@ -736,3 +750,7 @@ an :term:`importer`.
     attribute set and thus can be used by global level code during
     initialization.
 
+   .. note::
+
+      It is recommended that :func:`module_for_loader` be used over this
+      decorator as it subsumes this functionality.