104 lines
3.0 KiB
Markdown
104 lines
3.0 KiB
Markdown
# 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.
|
|
|
|
|
|
|
|
|
|
|