Learning Python - Mark Lutz [315]
It extends the syntax of from statements to allow them to explicitly request that imports search the package’s directory only. This is known as “relative” import syntax.
These changes are fully present in Python 3.0. The new from statement relative syntax is also available in Python 2.6, but the default search path change must be enabled as an option. It’s currently scheduled to be added in the 2.7 release[53]—this change is being phased in this way because the search path portion is not backward compatible with earlier Pythons.
The impact of this change is that in 3.0 (and optionally in 2.6), you must generally use special from syntax to import modules located in the same package as the importer, unless you spell out a complete path from a package root. Without this syntax, your package is not automatically searched.
Relative Import Basics
In Python 3.0 and 2.6, from statements can now use leading dots (“.”) to specify that they require modules located within the same package (known as package relative imports), instead of modules located elsewhere on the module import search path (called absolute imports). That is:
In both Python 3.0 and 2.6, you can use leading dots in from statements to indicate that imports should be relative to the containing package—such imports will search for modules inside the package only and will not look for same-named modules located elsewhere on the import search path (sys.path). The net effect is that package modules override outside modules.
In Python 2.6, normal imports in a package’s code (without leading dots) currently default to a relative-then-absolute search path order—that is, they search the package’s own directory first. However, in Python 3.0, imports within a package are absolute by default—in the absence of any special dot syntax, imports skip the containing package itself and look elsewhere on the sys.path search path.
For example, in both Python 3.0 and 2.6, a statement of the form:
from . import spam # Relative to this package
instructs Python to import a module named spam located in the same package directory as the file in which this statement appears. Similarly, this statement:
from .spam import name
means “from a module named spam located in the same package as the file that contains this statement, import the variable name.”
The behavior of a statement without the leading dot depends on which version of Python you use. In 2.6, such an import will still default to the current relative-then-absolute search path order (i.e., searching the package’s directory first), unless a statement of the following form is included in the importing file:
from __future__ import absolute_import # Required until 2.7?
If present, this statement enables the Python 3.0 absolute-by-default default search path change, described in the next paragraph.
In 3.0, an import without a leading dot always causes Python to skip the relative components of the module import search path and look instead in the absolute directories that sys.path contains. For instance, in 3.0’s model, a statement of the following form will always find a string module somewhere on sys.path, instead of a module of the same name in the package:
import string # Skip this package's version
Without the from __future__ statement in 2.6, if there’s a string module in the package, it will be imported instead. To get the same behavior in 3.0 and in 2.6 when the absolute import change is enabled, run a statement of the following form to force a relative import:
from . import string # Searches this package only
This works in both Python 2.6 and 3.0 today. The only difference in the 3.0 model is that it is required in order to load a module that is located in the same package directory as the file in which this appears, when the module is given with a simple name.
Note that leading dots can be used to force relative imports