Clarify the import statement semantics, especially for implicit imports in the 'from X import Y' variant

1 files changed, 74 insertions, 29 deletions

diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst
index f212e5a..81dc748 100644
--- a/Doc/reference/simple_stmts.rst
+++ b/Doc/reference/simple_stmts.rst
@@ -660,41 +660,86 @@ The :keyword:`import` statement
    relative_module: "."* `module` | "."+
    name: `identifier`
 
-Import statements are executed in two steps: (1) find a module, loading and
-initializing it if necessary; (2) define a name or names in the local
-namespace (of the scope where the :keyword:`import` statement occurs).
-Step (1) may be performed recursively if the named module is a submodule or
-subpackage of a parent package.
+The basic import statement (no :keyword:`from` clause) is executed in two
+steps:
+
+#. find a module, loading and initializing it if necessary
+#. define a name or names in the local namespace for the scope where
+   the :keyword:`import` statement occurs.
+
+When the statement contains multiple clauses (separated by
+commas) the two steps are carried out separately for each clause, just
+as though the clauses had been separated out into individiual import
+statements.
+
+The details of the first step, finding and loading modules is described in
+greater detail in the section on the :ref:`import system <importsystem>`,
+which also describes the various types of packages and modules that can
+be imported, as well as all the hooks that can be used to customize
+the import system. Note that failures in this step may indicate either
+that the module could not be located, *or* that an error occurred while
+initializing the module, which includes execution of the module's code.
+
+If the requested module is retrieved successfully, it will be made
+available in the local namespace in one of three ways:
+
+* If the module name is followed by :keyword:`as`, then the name
+  following :keyword:`as` is bound directly to the imported module.
+* If no other name is specified, and the module being imported is a top
+  level module, the module's name is bound in the local namespace as a
+  reference to the imported module
+* If the module being imported is *not* a top level module, then the name
+  of the top level package that contains the module is bound in the local
+  namespace as a reference to the top level package. The imported module
+  must be accessed using its full qualified name rather than directly
 
-The :keyword:`import` statement comes in two forms differing on whether it
-uses the :keyword:`from` keyword. The first form (without :keyword:`from`)
-repeats these steps for each identifier in the list.  The form with
-:keyword:`from` performs step (1), and then performs step (2) repeatedly.
-
-The details of step (1), finding and loading modules is described in greater
-detail in the section on the :ref:`import system <importsystem>`, which
-also describes the various types of packages and modules that can be imported,
-as well as all the hooks that can be used to customize Python's import.
-
-When step (1) finishes without raising an exception, step (2) can begin.
-
-The first form of :keyword:`import` statement binds the module name in the
-local namespace to the module object, and then goes on to import the next
-identifier, if any.  If the module name is followed by :keyword:`as`, the name
-following :keyword:`as` is used as the local name for the module.
 
 .. index::
    pair: name; binding
+   keyword: from
    exception: ImportError
 
-The :keyword:`from` form does not bind the module name: it goes through the
-list of identifiers, looks each one of them up in the module found in step
-(1), and binds the name in the local namespace to the object thus found.  As
-with the first form of :keyword:`import`, an alternate local name can be
-supplied by specifying ":keyword:`as` localname".  If a name is not found,
-:exc:`ImportError` is raised.  If the list of identifiers is replaced by a
-star (``'*'``), all public names defined in the module are bound in the local
-namespace of the :keyword:`import` statement.
+The :keyword:`from` form uses a slightly more complex process:
+
+#. find the module specified in the :keyword:`from` clause loading and
+   initializing it if necessary;
+#. for each of the identifiers specified in the :keyword:`import` clauses:
+
+   #. check if the imported module has an attribute by that name
+   #. if not, attempt to import a submodule with that name and then
+      check the imported module again for that attribute
+   #. if the attribute is not found, :exc:`ImportError` is raised.
+   #. otherwise, a reference to that value is bound in the local namespace,
+      using the name in the :keyword:`as` clause if it is present,
+      otherwise using the attribute name
+
+Examples::
+
+   import foo                 # foo imported and bound locally
+   import foo.bar.baz         # foo.bar.baz imported, foo bound locally
+   import foo.bar.baz as fbb  # foo.bar.baz imported and bound as fbb
+   from foo.bar import baz    # foo.bar.baz imported and bound as baz
+   from foo import attr       # foo imported and foo.attr bound as attr
+
+If the list of identifiers is replaced by a star (``'*'``), all public
+names defined in the module are bound in the local namespace for the scope
+where the :keyword:`import` statement occurs.
+
+.. index:: single: __all__ (optional module attribute)
+
+The *public names* defined by a module are determined by checking the module's
+namespace for a variable named ``__all__``; if defined, it must be a sequence
+of strings which are names defined or imported by that module.  The names
+given in ``__all__`` are all considered public and are required to exist.  If
+``__all__`` is not defined, the set of public names includes all names found
+in the module's namespace which do not begin with an underscore character
+(``'_'``).  ``__all__`` should contain the entire public API. It is intended
+to avoid accidentally exporting items that are not part of the API (such as
+library modules which were imported and used within the module).
+
+The :keyword:`from` form with ``*`` may only occur in a module scope.
+Attempting to use it in class or function definitions will raise a
+:exc:`SyntaxError`.
 
 .. index:: single: __all__ (optional module attribute)