# 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:
```txt
├── 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:
```txt
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:

```txt
[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
```sh
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.