\section{Packages}

Packages are a way of structuring Python's module namespace

by using ``dotted module names''. For example, the module name \module{A.B}

designates a submodule named \samp{B} in a package named \samp{A}. Just like the

use of modules saves the authors of different modules from having to

worry about each other's global variable names, the use of dotted

module names saves the authors of multi-module packages like NumPy or

PIL from having to worry about each other's module names.

Suppose you want to design a collection of modules (a ``package'') for

the uniform handling of sound files and sound data. There are many

different sound file formats (usually recognized by their extension,

e.g. \file{.wav}, \file{.aiff}, \file{.au}), so you may need to create

and maintain a growing collection of modules for the conversion

between the various file formats. There are also many different

operations you might want to perform on sound data (e.g. mixing,

adding echo, applying an equalizer function, creating an artificial

stereo effect), so in addition you will be writing a never-ending

stream of modules to perform these operations. Here's a possible

structure for your package (expressed in terms of a hierarchical

filesystem):

\begin{verbatim}

\end{verbatim}

The \file{__init__.py} files are required to make Python treat the

directories as containing packages; this is done to prevent

directories with a common name, such as \samp{string}, from

unintentionally hiding valid modules that occur later on the module

search path. In the simplest case, \file{__init__.py} can just be an

empty file, but it can also execute initialization code for the

package or set the \code{__all__} variable, described later.

Users of the package can import individual modules from the

package, for example:

\begin{verbatim}

\end{verbatim}

This loads the submodule \module{Sound.Effects.echo}. It must be referenced

with its full name, e.g.

\begin{verbatim}

\end{verbatim}

An alternative way of importing the submodule is:

\begin{verbatim}

\end{verbatim}

This also loads the submodule \module{echo}, and makes it available without

its package prefix, so it can be used as follows:

\begin{verbatim}

\end{verbatim}

Yet another variation is to import the desired function or variable directly:

\begin{verbatim}

\end{verbatim}

Again, this loads the submodule \module{echo}, but this makes its function

echofilter directly available:

\begin{verbatim}

\end{verbatim}

Note that when using \code{from \var{package} import \var{item}}, the

item can be either a submodule (or subpackage) of the package, or some

other name defined in the package, like a function, class or

variable. The \code{import} statement first tests whether the item is

defined in the package; if not, it assumes it is a module and attempts

to load it. If it fails to find it, \exception{ImportError} is raised.

Contrarily, when using syntax like \code{import

\var{item.subitem.subsubitem}}, each item except for the last must be

a package; the last item can be a module or a package but can't be a

class or function or variable defined in the previous item.

\subsection{Importing * From a Package}

Now what happens when the user writes \code{from Sound.Effects import

*}? Ideally, one would hope that this somehow goes out to the

filesystem, finds which submodules are present in the package, and

imports them all. Unfortunately, this operation does not work very

well on Mac and Windows platforms, where the filesystem does not

always have accurate information about the case of a filename! On

these platforms, there is no guaranteed way to know whether a file

\file{ECHO.PY} should be imported as a module \module{echo},

\module{Echo} or \module{ECHO}. (For example, Windows 95 has the

annoying practice of showing all file names with a capitalized first

letter.) The DOS 8+3 filename restriction adds another interesting

problem for long module names.

The only solution is for the package author to provide an explicit

index of the package. The import statement uses the following

convention: if a package's \file{__init__.py} code defines a list named

\code{__all__}, it is taken to be the list of module names that should be imported

when \code{from \var{package} import *} is

encountered. It is up to the package author to keep this list

up-to-date when a new version of the package is released. Package

authors may also decide not to support it, if they don't see a use for

importing * from their package. For example, the file

\code{Sounds/Effects/__init__.py} could contain the following code:

\begin{verbatim}

\end{verbatim}

This would mean that \code{from Sound.Effects import *} would

import the three named submodules of the \module{Sound} package.

If \code{__all__} is not defined, the statement \code{from Sound.Effects

import *} does \emph{not} import all submodules from the package

\module{Sound.Effects} into the current namespace; it only ensures that the

package \module{Sound.Effects} has been imported (possibly running its

initialization code, \file{__init__.py}) and then imports whatever names are

defined in the package. This includes any names defined (and

submodules explicitly loaded) by \file{__init__.py}. It also includes any

submodules of the package that were explicitly loaded by previous

import statements, e.g.

\begin{verbatim}

\end{verbatim}

In this example, the echo and surround modules are imported in the

current namespace because they are defined in the \module{Sound.Effects}

package when the \code{from...import} statement is executed. (This also

works when \code{__all__} is defined.)

Note that in general the practicing of importing * from a module or

package is frowned upon, since it often causes poorly readable code.

However, it is okay to use it to save typing in interactive sessions,

and certain modules are designed to export only names that follow

certain patterns.

Remember, there is nothing wrong with using \code{from Package

import specific_submodule}! In fact, this is the

recommended notation unless the importing module needs to use

submodules with the same name from different packages.

\subsection{Intra-package References}

The submodules often need to refer to each other. For example, the

\module{surround} module might use the \module{echo} module. In fact, such references

are so common that the \code{import} statement first looks in the

containing package before looking in the standard module search path.

Thus, the surround module can simply use \code{import echo} or

\code{from echo import echofilter}. If the imported module is not

found in the current package (the package of which the current module

is a submodule), the \code{import} statement looks for a top-level module

with the given name.

When packages are structured into subpackages (as with the \module{Sound}

package in the example), there's no shortcut to refer to submodules of

sibling packages - the full name of the subpackage must be used. For

example, if the module \module{Sound.Filters.vocoder} needs to use the \module{echo}

module in the \module{Sound.Effects} package, it can use \code{from

Sound.Effects import echo}.