import_stmt: "import" module ["as" name] ("," module ["as" name] )* | "from" module "import" identifier ["as" name] ("," identifier ["as" name] )* | "from" module "import" "*" module: (identifier ".")* identifier
Import statements are executed in two steps: (1) find a module, and initialize it if necessary; (2) define a name or names in the local namespace (of the scope where the import statement occurs). The first form (without from) repeats these steps for each identifier in the list. The form with from performs step (1) once, and then performs step (2) repeatedly.
The system maintains a table of modules that have been initialized,
indexed by module name. This table is
accessible as sys.modules
. When a module name is found in
this table, step (1) is finished. If not, a search for a module
definition is started. When a module is found, it is loaded. Details
of the module searching and loading process are implementation and
platform specific. It generally involves searching for a ``built-in''
module with the given name and then searching a list of locations
given as sys.path
.
If a built-in module is found, its built-in initialization code is executed and step (1) is finished. If no matching file is found, ImportError is raised. If a file is found, it is parsed, yielding an executable code block. If a syntax error occurs, SyntaxError is raised. Otherwise, an empty module of the given name is created and inserted in the module table, and then the code block is executed in the context of this module. Exceptions during this execution terminate step (1).
When step (1) finishes without raising an exception, step (2) can begin.
The first form of 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
as, the name following as is used as the local
name for the module. To avoid confusion, you cannot import modules
with dotted names as a different local name. So import
module as m
is legal, but import module.submod as s
is not.
The latter should be written as from module import submod as s
;
see below.
The 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 import, an alternate local name can be supplied by specifying "as localname". If a name is not found, ImportError is raised. If the list of identifiers is replaced by a star ("*"), all names defined in the module are bound, except those beginning with an underscore ("_").
Names bound by import statements may not occur in global statements in the same scope.
The from form with "*" may only occur in a module scope.
Hierarchical module names: when the module names contains one or more dots, the module search
path is carried out differently. The sequence of identifiers up to
the last dot is used to find a ``package'' ; the final
identifier is then searched inside the package. A package is
generally a subdirectory of a directory on sys.path
that has a
file __init__.py. [XXX Can't be bothered to spell this out right now; see the URL
http://www.python.org/doc/essays/packages.html for more details, also
about how the module search works from inside a package.]
[XXX Also should mention __import__().]
See About this document... for information on suggesting changes.