Learning Python - Mark Lutz [310]
This is a somewhat advanced feature, but the hierarchy it provides turns out to be handy for organizing the files in a large system and tends to simplify module search path settings. As we’ll see, package imports are also sometimes required to resolve import ambiguities when multiple program files of the same name are installed on a single machine.
Because it is relevant to code in packages only, we’ll also introduce Python’s recent relative imports model and syntax here. As we’ll see, this model modifies search paths and extends the from statement for imports within packages.
Package Import Basics
So, how do package imports work? In the place where you have been naming a simple file in your import statements, you can instead list a path of names separated by periods:
import dir1.dir2.mod
The same goes for from statements:
from dir1.dir2.mod import x
The “dotted” path in these statements is assumed to correspond to a path through the directory hierarchy on your machine, leading to the file mod.py (or similar; the extension may vary). That is, the preceding statements indicate that on your machine there is a directory dir1, which has a subdirectory dir2, which contains a module file mod.py (or similar).
Furthermore, these imports imply that dir1 resides within some container directory dir0, which is a component of the Python module search path. In other words, the two import statements imply a directory structure that looks something like this (shown with DOS backslash separators):
dir0\dir1\dir2\mod.py # Or mod.pyc, mod.so, etc.
The container directory dir0 needs to be added to your module search path (unless it’s the home directory of the top-level file), exactly as if dir1 were a simple module file.
More generally, the leftmost component in a package import path is still relative to a directory included in the sys.path module search path list we met in Chapter 21. From there down, though, the import statements in your script give the directory paths leading to the modules explicitly.
Packages and Search Path Settings
If you use this feature, keep in mind that the directory paths in your import statements can only be variables separated by periods. You cannot use any platform-specific path syntax in your import statements, such as C:\dir1, My Documents.dir2 or ../dir1—these do not work syntactically. Instead, use platform-specific syntax in your module search path settings to name the container directories.
For instance, in the prior example, dir0—the directory name you add to your module search path—can be an arbitrarily long and platform-specific directory path leading up to dir1. Instead of using an invalid statement like this:
import C:\mycode\dir1\dir2\mod # Error: illegal syntax
add C:\mycode to your PYTHONPATH variable or a .pth file (assuming it is not the program’s home directory, in which case this step is not necessary), and say this in your script:
import dir1.dir2.mod
In effect, entries on the module search path provide platform-specific directory path prefixes, which lead to the leftmost names in import statements. import statements provide directory path tails in a platform-neutral fashion.[52]
Package __init__.py Files
If you choose to use package imports, there is one more constraint you must follow: each directory named within the path of a package import statement must contain a file named __init__.py, or your package imports will fail. That is, in the example we’ve been using, both dir1 and dir2 must contain a file called __init__.py; the container directory dir0 does not require such a file because it’s not listed in the import statement itself. More formally, for a directory structure such as this:
dir0\dir1\dir2\mod.py
and an import statement of the form:
import dir1.dir2.mod
the following rules apply:
dir1 and dir2 both must contain an __init__.py file.
dir0, the container, does not require