So far we have been working with fairly short, simple programs contained in single files. That style works great for scripts; but most real applications are more complex, and thus better split among several files.

Package Layout

Consider the file layout of a sample program:


Python considers any folder that is on the PYTHONPATH and contains an file to be a package, and thus importable.

The file’s primary purpose is to be a marker - any folder containing an file is an importable package. The file likewise defines the top level of said package’s namespace.

Almost every Python package contains an file; and the file name tells us nothing about the contents of the file, except that it is package marker. Therefore it is considered inappropriate to put real functionality - class definitions, functions, etc - into an file.

It is commonplace for to be left completely empty. If it does contain code, it will typically be limited to docstrings, version constants, and import statements. Since the file is the top level of it’s package’s namespace, by importing an object into we promote that into the module’s top level namespace.

Consider what an file from the example program above might look like:


A program that puts the foo into bar!  (Caution, use at your own risk.  Your
mileage may vary.)

VERSION = '0.1'

from foo import Spam
from bar.baz import Eggs

Importing Packages

In this example, two classes will be available in the top level namespace of the package: Spam, which is defined in foobar/; and Eggs which is defined in foobar/bar/ Both classes were imported above into Consequently code outside this package can import those classes like so:

from foobar import VERSION
from foobar import Spam
from foobar import Eggs
# Not imported in, so we have to use the full path:
from import Ham

Note that in Python, unlike in Java, it is commonplace for multiple class definitions to live in one file. Nor is there necessarily any relationship between the name of a file and the name(s) of the object(s) it contains.