One important consideration when designing a package is don't. The Zen of Python poem (also known as import this) includes this line:

We can see this in the Python standard library. The structure of the library is relatively flat; there are few nested modules. Deeply nested packages can be overused. We should be skeptical of excessive nesting.

A Python package is a directory with an extra file, __init__.py. The directory name must be a proper Python name. OS names include a lot of characters that are not allowed in Python names.

We often see three design patterns for packages:

• Simple packages are a directory with an empty __init__.py file. This package name becomes a qualifier for a collection of modules inside the package. We'll use the following code to pick one of the modules from the package:

import package.module 

• A module-package hybrid can have an __init__.py file that is effectively a module definition. This top-level module will import elements from modules inside the package, exposing them via the __init__  module. We'll use the following code to import the whole package as if it was a single module:

import package 

• Another variation on the module-package hybrid uses the __init__.py file to choose among alternative implementations. We use the package as if it was a single module via code, as in the following example:

import package 

The first kind of package is relatively simple. We add an __init__.py file to a directory, and, with that, we're done creating a package. The other two are a bit more involved; we'll look at these in detail.

Let's see how to design a module-package hybrid.