Een project beschrijven met pyproject.toml

Je collega ontvangt je pakket, maar weet nog niet hoe het heet, welke Pythonversie erbij past of hoe het gebouwd wordt. Leg die afspraken naast de broncode vast. Dan kunnen gereedschappen ze lezen zonder dat iemand jouw persoonlijke computer hoeft na te bouwen.

Gegevens naast de code

Een projectbeschrijving bevat gegevens over je software. Pythonprojecten gebruiken daarvoor vaak pyproject.toml. Dit bestand voert geen Pythoncode uit en installeert zelf niets: een gereedschap leest het later om bijvoorbeeld een pakket te bouwen.

TOML is een tekstformaat met sleutels, waarden en tabellen. Een tabel begint met een naam tussen vierkante haken, zoals [project]. De sleutels eronder horen bij die tabel, tot de volgende tabel begint.

Tekst staat tussen aanhalingstekens; een lijst staat tussen vierkante haken. Daarom zijn dependencies = [] en dependencies = "[]" verschillende gegevens. De eerste waarde is een lege lijst, de tweede een tekst met twee haakjes.

Het eerste voorbeeld leest een losse projectbeschrijving met tomllib uit de standaardbibliotheek. De tabellen worden dictionaries en de lijst blijft een echte lijst. Dit voorbeeld leest uitsluitend gegevens; het bouwt geen pakket.

[project]
name = "walk-log"
version = "2.0.0"
dependencies = []

import tomllib
from pathlib import Path

config = tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8"))
project = config["project"]
print(project["name"], project["version"])
print(type(project["dependencies"]).__name__, len(project["dependencies"]))

walk-log 2.0.0
list 0

Identiteit en uitvoering

Onder [project] staan de distributienaam en versie. De distributienaam is de naam waarmee een pakket wordt aangeboden of geïnstalleerd. Die naam hoeft niet hetzelfde gespeld te zijn als de importnaam: hier heet de distributie ticket-kit, terwijl de meegeleverde Pythonmap ticket_kit heet.

Met requires-python beschrijf je welke Pythonversies jouw project accepteert. Het bereik ">=3.14,<3.15" omvat de 3.14-reeks en sluit 3.15 uit. Dit kiest of installeert geen interpreter; een installer kan de vereiste controleren.

Uitvoerafhankelijkheden zijn andere distributies die jouw geïnstalleerde programma nodig heeft. Ze staan in project.dependencies. Voor dit kleine pakket is die lijst leeg, omdat de meegeleverde code alleen de standaardbibliotheek gebruikt.

Bouwen is een aparte stap

Een build-backend maakt van de broncode een installeerbaar pakket. De tabel [build-system] noemt het gereedschap en zijn bouwvereisten. Die vereisten zijn iets anders dan de pakketten die je programma tijdens het uitvoeren gebruikt.

In deze oefening gebruik je de backend "uv_build" met bouwvereiste "uv_build==0.13.6". De dubbele gelijktekens zetten precies die versie vast. Deze backend verwacht hier de bronmap src/ticket_kit; de benodigde bestanden zijn al meegeleverd.

Een commando aanbieden

De tabel [project.scripts] koppelt een commandonaam aan een functie. De waarde "ticket_kit.cli:main" betekent: importeer de module ticket_kit.cli en gebruik daar de functie main. Schrijf geen haakjes achter de functienaam.

De tabel maakt het commando niet onmiddellijk beschikbaar. Pas bij installatie kan een installer daarvoor een startbestand maken. In deze les controleer je de declaratie; in de volgende lessen voer je de bijbehorende omgevings- en installatiehandelingen uit.

Veelgemaakte fout: een tabel opnieuw openen

Je mag dezelfde tabel niet opnieuw declareren. Het tweede voorbeeld bevat twee koppen [project] en laat de echte TOMLDecodeError zien. Voeg de velden samen onder één kop; extra aanhalingstekens repareren deze structuurfout niet.

[project]
name = "walk-log"

[project]
version = "2.0.0"

import tomllib
from pathlib import Path

config = tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8"))
print(config["project"]["version"])

TOMLDecodeError

Onthoud dit

• Projectmetadata beschrijft identiteit, Pythonvereisten en uitvoerafhankelijkheden.
• Bouwvereisten horen bij de build-backend en staan apart.
• Een consoledeclaratie verwijst naar een functie; installatie maakt het commando.

Hierna maak je een eigen virtuele omgeving waarin zo’n pakket geïnstalleerd kan worden.