Linux/Unix > Python Essential Reference, Second Edition > 8. Modules and Packages > Packages | See All Titles

< BACK | Make Note | Bookmark | CONTINUE >

155117184014003188065099048180054212144238241179195140058238111161105084124002233103235139

### Packages

Packages allow a collection of modules to be grouped under a common package name. This technique helps resolve namespace conflicts between module names used in different applications. A package is defined by creating a directory with the same name as the package and creating a file `_ _init_ _.py` in that directory. You can then place additional source files, compiled extensions, and subpackages in this directory as needed. For example, a package might be organized as follows:

    Graphics/
          _ _init_ _.py
          Primitive/
             _ _init_ _.py
             lines.py
             fill.py
             text.py
             ...
          Graph2d/
             _ _init_ _.py
             plot2d.py
             ...
          Graph3d/
             _ _init_ _.py
             plot3d.py
             ...
          Formats/
             _ _init_ _.py
             gif.py
             png.py
             tiff.py
             jpeg.py

The `import` statement is used to load modules from a package in a number of ways:

- `import Graphics.Primitive.fill`

  This loads the submodule `Graphics.Primitive.fill`. The contents of this module have to be explicitly named, such as `Graphics.Primitive.fill.floodfill(img,x,y,color)`.

- `from Graphics.Primitive import fill`

  This loads the submodule `fill` but makes it available without the package prefix; for example, `fill.floodfill(img,x,y,color)`.

- `from Graphics.Primitive.fill import floodfill`

  This loads the submodule `fill` but makes the `floodfill` function directly accessible; for example, `floodfill(img,x,y,color)`.

Whenever any part of a package is imported, the code in the file `_ _init_ _.py` is executed. Minimally, this file may be empty, but it can also contain code to perform package-specific initializations. All the `_ _init_ _.py` files encountered during an import are executed. Thus, the statement `import Graphics.Primitive.fill` shown earlier would execute the `_ _init_ _.py` files in both the `Graphics` directory and the `Primitive` directory.

One peculiar problem with packages is the handling of this statement:

    from Graphics.Primitive import *

The intended outcome of this statement is to import all the modules associated with a package into the current namespace. However, because filename conventions vary from system to system (especially with regard to case sensitivity), Python cannot accurately determine what modules those might be. As a result, this statement just imports all the references defined in the `_ _init_ _.py` file in the `Primitive` directory. This behavior can be modified by defining a list `_ _all_ _` that contains all the module names associated with the package. This list should be defined in the package `_ _init_ _.py` file, like this:

    # Graphics/Primitive/_ _init_ _.py
    _ _all_ _ = ["lines","text","fill",...]

Now when the user issues a `from Graphics.Primitive import *` statement, all the listed submodules are loaded as expected.

Importing a package name alone doesn’t import all the submodules contained in the package. For example, the following code doesn’t work:

    import Graphics
    Graphics.Primitive.fill.floodfill(img,x,y,color)  # Fails!

However, because the `importGraphics` statement executes the `_ _init_ _.py` file in the `Graphics` directory, it could be modified to import all the submodules automatically as follows:

    # Graphics/_ _init_ _.py
    import Primitive, Graph2d, Graph3d

    # Graphics/Primitive/_ _init_ _.py
    import lines, fill, text, ...

Now the `importGraphics` statement imports all the submodules and makes them available using their fully qualified names.

The modules contained within the same directory of a package can refer to each other without supplying a full package name. For example, the `Graphics.Primitive.fill` module could import the `Graphics.Primitive.lines` module simply by using `import lines`. However, if a module is located in a different subdirectory, its full package name must be used. For example, if the `plot2d` module of `Graphics.Graph2d` needs to use the `lines` module of `Graphics.Primitive`, it must use a statement such as `from Graphics.Primitive import lines`. If necessary, a module can examine its `_ _name_ _` variable to find its fully qualified module name. For example, the following code imports a module from a sibling subpackage knowing only the name of the sibling (and not that of its top-level package):

    # Graphics/Graph2d/plot2d.py

    # Determine the name of the package where my package is located
    import string
    base_package = string.join(string.split(_ _name_ _,'.')[:-2],'.')

    # Import the ../Primitive/fill.py module
    exec "from %s.Primitive import fill" % (base_package,)

Finally, when Python imports a package, it defines a special variable `_ _path_ _` that contains a list of directories that are searched when looking for package submodules. (The variable `_ _path_ _` is a package-specific version of the `sys.path` variable.) `_ _path_ _` is accessible to the code contained in `_ _init_ _.py` files and initially contains a single item with the directory name of the package. If necessary, a package can add additional directories to the `_ _path_ _` list to alter the search path used for finding submodules.

| Last updated on 3/28/2002 Python Essential Reference, Second Edition, © 2002 New Riders Publishing

< BACK | Make Note | Bookmark | CONTINUE >

© 2002, O'Reilly & Associates, Inc.