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

  1. Create a project on git.tu-berlin.de exactly as in Part 1 Tasks Task 1 (untick “Initialize repository with a README”). Call it something like number-magic.

  2. 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.

  3. 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
    
  4. 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:

pyproject.toml
[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.

  • name is what the package is called when installed; keep it the same as your package folder to avoid confusion.

  • dependencies lists other packages yours needs — empty for now, but you’ll add click shortly.

  • [tool.setuptools.packages.find] tells setuptools which folders are part of the package. The exclude line matters later: once you add a tests/ folder in the next chapter, without it the build fails with Multiple 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:

plain_magic/cli.py
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