**********************import_stmt ::= "import" module ["as" name] ( "," module ["as" name] )*
| "from" relative_module "import" identifier ["as"name]
("," identifier ["as" name] )*
| "from" relative_module "import" "(" identifier ["as"name]
("," identifier ["as" name] )* [","] ")"
| "from" module "import" "*"module ::= (identifier ".")*identifier
relative_module ::= "."* module | "."+name ::=identifier
Import statements are executedin two steps: (1) find a module, andinitialize itif necessary; (2) define a name or names inthe local
namespace (of the scope where the"import"statement occurs). The
statement comesin two forms differing on whether it uses the "from"keyword. The first form (without"from") repeats these steps foreach
identifierin the list. The form with "from" performs step (1) once,and then performs step (2) repeatedly.
To understand how step (1) occurs, one must first understand how
Python handles hierarchical naming of modules. To help organize modulesand provide a hierarchy innaming, Python has a concept of
packages. A package can contain other packagesand modules whilemodules cannot contain other modulesorpackages. From a file system
perspective, packages are directoriesandmodules are files.
Once the name of the moduleisknown (unless otherwise specified, the
term"module" will refer to both packages and modules), searching forthe moduleor package can begin. The first place checked is
"sys.modules", the cache of all modules that have been imported
previously. If the moduleis found there then it is used in step (2)
ofimport.
If the moduleis not found in the cache, then "sys.meta_path" issearched (the specificationfor "sys.meta_path" can be found in **PEP302**). The object is a list of *finder* objects which are queried inorder as to whether they know how to load the module by calling their"find_module()"method with the name of the module. If the module
happens to be contained within a package (as denoted by the existence
of a dotin the name), then a second argument to "find_module()" isgiven as the value of the"__path__" attribute fromthe parent package
(everything up to the last dotin the name of the module being imported).
If a finder can find the module it returns a *loader*(discussed later)or returns "None".
If none of the finders on"sys.meta_path"are able to find the module
then some implicitly defined finders are queried. Implementations of
Python varyinwhat implicit meta path finders are defined. The one
they all do define, though,is one that handles "sys.path_hooks","sys.path_importer_cache", and "sys.path".
The implicit finder searchesfor the requested module in the "paths"specifiedin one of two places ("paths" do nothave to be file system
paths). If the module being importedissupposed to be contained
within a package then the second argument passed to"find_module()","__path__" on the parent package, isused as the source of paths. If
the moduleis not contained in a package then "sys.path" isused as
the source of paths.
Once the source of pathsis chosen it isiterated over to find a
finder that can handle that path. The dict at"sys.path_importer_cache" caches finders for paths and is checked for a finder.
If the path does nothave a finder cached then"sys.path_hooks" is searched by calling each object inthe list with a
single argument of the path, returning a finderorraises"ImportError". If a finder is returned then it is cached in
"sys.path_importer_cache" and then used forthat path entry. If no
finder can be found but the path exists then a value of"None" isstoredin "sys.path_importer_cache" to signify that an implicit, file-based finder that handles modules stored as individual files should be
usedfor that path. If the path does notexist then a finder which
always returns"None" is placed in the cache forthe path.
If no finder can find the module then"ImportError" israised.
Otherwise some finder returned a loader whose"load_module()"methodis called with the name of the module to load (see **PEP 302** forthe
original definition of loaders). A loader has several responsibilities
to perform on a module it loads. First,ifthe module already existsin "sys.modules" (a possibility if the loader iscalled outside of theimport machinery) then it is to use that module for initialization and
not a new module. But if the module does not exist in "sys.modules",
then it isto be added to that dict before initialization begins. If
an error occurs during loading of the moduleandit was added to"sys.modules" it is to be removed fromthe dict. If an error occurs
but the module was alreadyin "sys.modules" it is left inthe dict.
The loader must set several attributes on the module."__name__" isto
be set to the name of the module."__file__" is to be the "path"to
the file unless the moduleis built-in (and thus listed in
"sys.builtin_module_names") in which case the attribute is notset. If
whatis being imported is a package then "__path__" isto be set to a
list of paths to be searched when lookingfor modules andpackages
contained within the package being imported."__package__" isoptional
but should be set to the name of package that contains the moduleorpackage (the empty stringis used for module not contained ina
package)."__loader__" isalso optional but should be set to the
loader object thatisloading the module.
If an error occurs during loading then the loader raises"ImportError"
if some other exception is notalready being propagated. Otherwise the
loader returns the module that was loadedandinitialized.
When step (1) finishes without raising an exception, step (2) can
begin.
The first form of"import" statement binds the module name inthe
local namespace to the module object,and then goes on to importthe
next identifier,if any. If the module name is followed by "as", the
name following"as" is used as the local name forthe module.
The"from" form does notbind the module name: it goes through the
list of identifiers, looks each one of them upin the module found instep (1), and binds the name inthe 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 notfound,"ImportError" is raised. If the list of identifiers isreplaced by a star ("'*'"), all public names defined inthe module are
boundin 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 orimported by that
module. The names givenin "__all__" are all considered public andare required to exist. If"__all__" is notdefined, the set of public
names includes all names foundin the module's namespace which do not
begin with an underscore character ("'_'"). "__all__"should contain
the entire public API. Itisintended to avoid accidentally exporting
items that arenotpart of the API (such as library modules which were
importedandused within the module).
The"from" form with "*" may only occur ina module scope. If the
wild card form ofimport --- "import *" --- is used in a function andthe function containsor isa nested block with free variables, the
compiler willraise a "SyntaxError".
When specifying what module toimport you do nothave to specify the
absolute name of the module. When a moduleor package iscontained
within another package itis possible to make a relative importwithinthe same top package without having to mention the package name. By
using leading dotsin the specified module or package after "from"you
can specify how high to traverse up the current package hierarchy
without specifying exact names. One leading dot means the current
package where the module making theimportexists. Two dots means up
one package level. Three dotsis up two levels, etc. So ifyou execute"from . import mod" from a module in the "pkg"package then you will
end up importing"pkg.mod". If you execute "from ..subpkg2 import mod"
from within "pkg.subpkg1" you will import "pkg.subpkg2.mod". The
specificationfor relative imports is contained within **PEP 328**."importlib.import_module()" isprovided to support applications that
determine which modules need to be loaded dynamically.
Future statements=================A*future statement* isa directive to the compiler that a particular
module should be compiled using syntaxorsemantics that will be
availableina specified future release of Python. The future
statementisintended to ease migration to future versions of Python
that introduce incompatible changes to the language. It allows use ofthe new features on a per-module basis before the release inwhich the
feature becomes standard.
future_statement ::= "from" "__future__" "import" feature ["as"name]
("," feature ["as" name])*
| "from" "__future__" "import" "(" feature ["as"name]
("," feature ["as" name])* [","] ")"feature ::=identifier
name ::=identifier
A future statement must appear near the top of the module. The only
lines that can appear before a future statement are:* the module docstring (ifany),*comments,* blank lines, and
*other future statements.
The features recognized by Python2.6 are "unicode_literals", "print_function",
"absolute_import", "division", "generators","nested_scopes" and "with_statement". "generators", "with_statement","nested_scopes" are redundant in Python version 2.6 andabove because
they are always enabled.
A future statementis recognized andtreated specially at compile
time: Changes to the semantics of core constructs are often
implemented by generating different code. It may even be the case
that a new feature introduces new incompatible syntax (such as a new
reserved word),inwhich case the compiler may need to parse the
module differently. Such decisions cannot be pushed off until
runtime.
For any given release, the compiler knows which feature names have
been defined,and raises a compile-time error ifa future statement
contains a featurenotknown to it.
The direct runtime semantics are the same asfor any importstatement:
thereis a standard module "__future__", described later, andit will
be importedin the usual way at the time the future statement isexecuted.
The interesting runtime semantics depend on the specific feature
enabled by the future statement.
Note that thereisnothing special about the statement:import __future__[as name]
Thatis not a future statement; it's an ordinary import statement with
no special semantics orsyntax restrictions.
Code compiled by an"exec" statement or calls to the built-infunctions"compile()" and "execfile()" that occur in a module "M"containing a future statement will, by default, use the new syntaxorsemantics associated with the future statement. This can, starting
with Python2.2 be controlled by optional arguments to "compile()" ---see the documentation of that functionfordetails.
A future statement typed at an interactive interpreter prompt will
take effectforthe rest of the interpreter session. If an
interpreteris started with the "-i" option, ispassed a script name
to execute,and the script includes a future statement, it will be ineffectin the interactive session started after the script isexecuted.
See also:**PEP 236** - Back to the __future__The original proposalfor the __future__ mechanism.