Previous Page
Next Page

7.3. Packages

A package is a module that contains other modules. Some or all of the modules in a package may be subpackages, resulting in a hierarchical tree-like structure. A package named P resides in a subdirectory, also called P, of some directory in sys.path. Packages can also live in ZIP files; in the following, I explain the case in which the package lives on the filesystem, since the case in which a package lives in a ZIP file is strictly analogous, relying on the hierarchical filesystem-like structure inside the ZIP file.

The module-body of P is in the file P/_ _init_ _.py. You must have a file named P/_ _init_ _.py, even if it's empty (representing an empty module-body) in order to indicate to Python that directory P is indeed a package. The module-body of a package is loaded when you first import the package (or any of the package's modules) and behaves in all respects like any other Python module. The other .py files in directory P are the modules of package P. Subdirectories of P containing _ _init_ _.py files are subpackages of P. (In Python 2.5, all subdirectories of P are subpackages of P, whether such subdirectories contain _ _init_ _.py files or not.) Nesting can continue to any depth.

You can import a module named M in package P as P.M. More dots let you navigate a hierarchical package structure. (A package's module-body is always loaded before any module in the package is loaded.) If you use the syntax import P.M, variable P is bound to the module object of package P, and attribute M of object P is bound to module P.M. If you use the syntax import P.M as V, variable V is bound directly to module P.M.

Using from P import M to import a specific module M from package P is a perfectly acceptable practice: the from statement is specifically okay in this case.

A module M in a package P can import any other module X of P with the statement import X. Python searches the module's own package directory before searching the items in sys.path. However, this applies only to sibling modules, not to ancestors or other more complicated relationships. The simplest, cleanest way to share objects (such as functions or constants) among modules in a package P is to group the shared objects in a file named P/Common.py. Then you can import Common from every module in the package that needs to access the objects, and then refer to the objects as Common.f, Common.K, and so on.

7.3.1.

7.3.1.1. Special attributes of package objects

A package P's _ _file_ _ attribute is the string that is the path of P's module-bodythat is, the path of the file P/_ _init_ _.py.

A package P's module-bodythat is, the Python source that is in the file P/_ _init_ _.pycan optionally set a global variable named _ _all_ _ (just like any other module can) to control what happens if some other module executes the statement from P import *. In particular, if _ _all_ _ is not set, from P import * does not import P's modules, but only other names that are set in P's module-body. However, in any case, using from P import *is not recommended usage.

A package P's _ _path_ _ attribute is the list of strings that are the paths to the directories from which P's modules and subpackages are loaded. Initially, Python sets _ _path_ _ to a list with a single element: the path of the directory containing the file _ _init_ _.py that is the module-body of the package. However, your code can modify this list to affect all future searches for modules and subpackages of this package. This advanced technique is rarely necessary, but it can occasionally be useful when you want to place a package's modules in several disjoint directories.

7.3.2. Absolute Versus Relative Imports

In Python 2.5, if you start a module with:

from _ _future_ _ import absolute_import

then the rules change: import X means a normal ("absolute") import of a module from somewhere in sys.path; to get a relative import, meaning an import of a module from within the current package, code from . import X instead. With this feature, you can also code richer and more complex relative imports, although getting too fancy could easily damage your code's clarity. These rules will become the default in some future version of Python; see http://www.python.org/doc/peps/pep-0328/ for more details, including the best current forecast for the schedule of these changes.


Previous Page
Next Page