Building Robust Object-Oriented Python Applications and Libraries/

...

/

Organizing Modules

Organizing Modules

Learn how to organize modules by absolute and relative imports in Python.

We'll cover the following...

Why do we need packages?

As a project grows into a collection of more and more modules, we may find that we want to add another level of abstraction, some kind of nested hierarchy on our modules’ levels. However, we can’t put modules inside modules; one file can hold only one file after all, and modules are just files.

Files, however, can go in folders, and so can modules. A package is a collection of modules in a folder. The name of the package is the name of the folder. We need to tell Python that a folder is a package to distinguish it from other folders in the directory. To do this, place a (normally empty) file in the folder named __init__.py. If we forget this file, we won’t be able to import modules from that folder.

Press + to interact
A package of two modules
A package of two modules

Let’s put our modules inside an ecommerce package in our working folder, which will also contain a main.py file to start the program. Let’s additionally add another package inside the ecommerce package for various payment options. We need to exercise some caution in creating deeply nested packages. The general advice in the Python community is “flat is better than nested.” In this example, we need to create a nested package because there are some common features to all of the various payment alternatives.

The folder hierarchy will look like this, rooted under a directory in the project folder, commonly named src:

src/
 +-- main.py
 +-- ecommerce/
     +-- __init__.py
     +-- database.py
     +-- products.py
     +-- payments/
     |   +-- __init__.py
     |   +-- common.py
     |   +-- square.py
     |   +-- stripe.py
     +-- contact/
         +-- __init__.py
         +-- email.py
A folder hierarchy for packages

The src directory will be part of an overall project directory. In addition to src, the project will often have directories with names like docs and tests. It’s common for the project parent directory to also have configuration files for tools like mypy, among others.

When importing modules or classes between ...