Basic Packaging¶
Unlike Parts 1–3, nothing is generated for you here — you build the whole thing by hand, which is the point: by the end you’ll have created every piece the earlier templates handed you for free.
Set up the starting point¶
Create a project on
git.tu-berlin.deexactly as in Part 1 Tasks Task 1 (untick “Initialize repository with a README”). Call it something likenumber-magic.On your own machine, create a folder to work in and move into it:
cd %USERPROFILE%\projects # Windows mkdir number_magic_project cd number_magic_project
cd ~/projects # macOS/Linux mkdir number_magic_project cd number_magic_project
Throughout these tasks this folder is referred to as
some_directory— it’s your project root, the folder everything else goes inside.Open it in PyCharm, then create a file called
number_magic.py(right-click the folder → New → File; see Prerequisites) and paste in:number_magic.py¶def addition(arg1, arg2): """ This function adds the first and the second argument. :param arg1: the first summand :type arg1: float :param arg2: the second and last summand :type arg2: float :return: the sum of both summands :rtype: float """ return arg1 + arg2
Make it a git repository and connect it to GitLab:
git init git add . git commit -m "Add the number_magic function" git remote add origin git@git.tu-berlin.de:kiwi-git-workshops/your-project.git git branch -M main git push -u origin main
From here on, keep using the branch → commit → merge request workflow from Part 1 for each step below.
Make it a package¶
Right now this is just a plain Python file. To turn it into a package
(something that can be imported by name), you need to put it in a folder and
add an __init__.py file to that folder, which may be empty.
Important
The filename is __init__.py — that’s two underscores before and
after init. It’s easy to miscount; if the import below fails, check
this first.
Create a folder called plain_magic, move number_magic.py into it
(drag it in PyCharm), and add an empty __init__.py next to it. You
should have:
some_directory/
plain_magic/
__init__.py
number_magic.py
Try it. In a terminal, in some_directory, start Python’s interactive
interpreter — a prompt where you type Python code line by line and see the
result immediately — by running python with no arguments:
python # Windows ('python3' on macOS/Linux)
The prompt changes to >>>, meaning you’re now typing Python rather than
shell commands. Try importing your package:
import plain_magic
How do you know it worked? Nothing happens — you just get a fresh
>>> prompt. That silence means success. A failure looks like this:
>>> import plain_magic
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ModuleNotFoundError: No module named 'plain_magic'
Note
To get back out of the Python interpreter to your normal terminal, type
exit() and press Enter (Ctrl+Z then Enter also works on Windows,
Ctrl+D on macOS/Linux). If your prompt still shows >>>, shell
commands like cd won’t work.
Enable Installations¶
Check Package Import¶
The package only imports while you’re sitting in the folder above it, which isn’t much use. See the problem for yourself — leave the interpreter, move somewhere else, and try again:
cd %USERPROFILE% # Windows ('cd ~' on macOS/Linux)
python
import plain_magic
This time it should fail with ModuleNotFoundError. That’s the problem
installing solves. Type exit() and head back to your project:
cd %USERPROFILE%\projects\number_magic_project
Create a pyproject.toml¶
pyproject.toml is the file that tells Python’s packaging tools how to
build and install your code. Create it in some_directory (not inside
plain_magic) with this content:
[build-system]
requires = ["setuptools>=68"]
build-backend = "setuptools.build_meta"
[project]
name = "plain_magic"
version = "0.0.1"
description = "A small package to practise packaging"
requires-python = ">=3.10"
dependencies = []
[tool.setuptools.packages.find]
exclude = ["tests*"]
A few things worth understanding rather than just copying:
[build-system]names the tool that does the building (setuptools). You rarely change this.nameis what the package is called when installed; keep it the same as your package folder to avoid confusion.dependencieslists other packages yours needs — empty for now, but you’ll addclickshortly.[tool.setuptools.packages.find]tells setuptools which folders are part of the package. Theexcludeline matters later: once you add atests/folder in the next chapter, without it the build fails withMultiple top-level packages discovered in a flat-layout.
For a fuller reference on each field, see the Kiwi template documentation.
How can you check if you succeeded?¶
Install it and import it from somewhere else. First create and activate a virtual environment for the project (see Prerequisites), then install:
python -m venv .venv # Windows
.venv\Scripts\Activate.ps1
pip install -e .
python3 -m venv .venv # macOS/Linux
source .venv/bin/activate
pip install -e .
How do you know it worked? The output ends with
Successfully installed plain_magic-0.0.1.
Now repeat the Check Package Import experiment: cd somewhere else,
run python, and import plain_magic. This time it succeeds from
anywhere.
Important
Keep the virtual environment active while you do this — the package was
installed into that environment, so it’s only importable while your
prompt shows (.venv). Opening a fresh terminal means activating it
again; a ModuleNotFoundError here usually means you forgot.
Your project should now look like this:
some_directory/
plain_magic/
__init__.py
number_magic.py
pyproject.toml
Write a Command Line Interface¶
Now we want to use the package from the command line, like this:
some-magic-cmd adding-two-numbers --first-summand 1 --second-summand 2
This takes two pieces. First, create cli.py inside plain_magic:
import click
from plain_magic.number_magic import addition
@click.group()
def cli_group():
pass
@cli_group.command()
@click.option('--first-summand', type=float, required=True)
@click.option('--second-summand', type=float, required=True)
def adding_two_numbers(first_summand, second_summand):
click.echo(f'The sum is {addition(first_summand, second_summand)}')
The @click.command() and @click.option(...) lines above the function
are decorators — they tell the click library to expose this plain Python
function as a command with those options.
Second, tell your package that this should become a real terminal command,
by adding two sections to pyproject.toml:
dependencies = ["click"]
[project.scripts]
some-magic-cmd = "plain_magic.cli:cli_group"
The [project.scripts] entry is called an entry point: it maps the
command name on the left to the function on the right (read
plain_magic.cli:cli_group as “the cli_group function in the
plain_magic.cli module”).
Important
Entry points are wired up at install time, so you must re-run:
pip install -e .
This is the one thing an editable install doesn’t pick up automatically. Editing the body of an existing command takes effect immediately; adding a new command, or changing its name, needs a reinstall.
How do you know it worked?
some-magic-cmd adding-two-numbers --first-summand 1 --second-summand 2
prints The sum is 3.0. Also try some-magic-cmd --help, which lists
the available commands. If you get command not found, check your virtual
environment is active and that you re-ran pip install -e ..
For a reference implementation, see the template package.
Your project should now look like this:
some_directory/
plain_magic/
__init__.py
cli.py
number_magic.py
pyproject.toml