Package HowTo

This is a brief introduction to python packages. How to make them, how to install them, how to upload them, how to maintain them, how to work with them. For details consult https://packaging.python.org and other sites.

Why packages?

When working on your project, you typically end up with some scripts, functions and classes that are of more general interest. As a first step, you make some modules, i.e. separate python files, where you collect this code. These modules can be easily imported from other scripts in the very same directory.

For example, consider a module addition.py and a script anayze.py both in the same directory:

├── addition.py
└── analyze.py

In addition.py we define a function add_two():

def add_two(x):
    return x + 2

We can use this function in analyze.py by importing it from addition.py:

from addition import add_two

x = 5
y = add_two(x)

This works, however, only if scripts and modules are in the same directory (or if modules are in sub-directories). To make modules available in other places of your file system or for even for other people, you need to turn the modules into packages.

Minimal package

First we make a project directory for our new package. Usually the name of the project directory is the same as the one of the package. Here, however, we called packagehowto and the name of the package is numerix.

A package is a directory, and the name of the package is the name of this directory, here numerix. Inside the package directory we put all the modules, here addition.py.

What makes this directory a package is the presence of a file named __init__.py. This file is executed when the package is imported. For now we leave it empty.

The package directory resides in the src/ directory of the project:

packagehowto/
├── pyproject.toml
└── src/
    └── numerix
        ├── __init__.py
        └── addition.py

A package also needs a pyproject.toml file. This file contains some metadata about hte package and informations about how to build a package. As the bare minimum the content of the pyproject.toml file specifies setuptools to be used for building the project:

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

With this pyproject.toml file, and addition.py and __init__.py in the src/numerix directory, you can install the numerix package on your machine and import it from whereever you want.

For installation go to the project root, here packagehowto/ and run from your shell

pip3 install .

This installs the package of the current project folder . somewhere in your home directory. From anywhere in your home directory you now can import this package. The import line of our analyze.py file needs to look like this:

from numerix.addition import add_two

From the addition module of the numerix package the function add_two is imported.