diff options
| -rw-r--r-- | Doc/reference/simple_stmts.rst | 103 |
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) |