GNU Info

(python2.1-ref.info)import statement

---

Next: global statement Prev: continue statement Up: Simple statements

---

Enter node , (file) or (file)node

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

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  for additional
information.