#
6.12 The `import` statement

  `import_stmt` | ::= | `"import" module ["as" name] ( "," module ["as" name] )*`
  |  | `| "from" module "import" identifier ["as" name]`
  |  | `( "," identifier ["as" name] )*`
  |  | `| "from" module "import" "*"`
  `module` | ::= | `(identifier ".")* identifier`

  Download entire grammar as text.

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 public names defined in the module are bound in the local namespace of the `import` statement..

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 ("`_`").

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.]

The built-in function `__import__()` is provided to support applications that determine which modules need to be loaded dynamically; refer to Built-in Functions in the Python Library Reference for additional information.