Next: The global statement Up: Simple statements Previous: The continue statement

The import statement


import_stmt:    "import" identifier ("," identifier)*
              | "from" identifier "import" identifier ("," identifier)*
              | "from" identifier "import" "*"

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 name space (of the scope where the import statement occurs). The first form (without from) repeats these steps for each identifier in the list, the from form performs them once, with the first identifier specifying the module name.

The system maintains a table of modules that have been initialized, indexed by module name. (The current implementation makes this table 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. This first looks for a built-in module definition, and if no built-in module if the given name is found, it searches a user-specified list of directories for a file whose name is the module name with extension ".py". (The current implementation uses the list of strings sys.path as the search path; it is initialized from the shell environment variable $PYTHONPATH, with an installation-dependent default.)

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 name space to the module object, and then goes on to import the next identifier, if any. The from from 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 name space to the object thus found. 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.

(The current implementation does not enforce the latter two restrictions, but programs should not abuse this freedom, as future implementations may enforce them or silently change the meaning of the program.)



Next: The global statement Up: Simple statements Previous: The continue statement


guido@cwi.nl