Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 5: Packaging und Qualität – checkcert als Paket

Ziel: checkcert aus Tag 4 zu einem versionierten, geprüften und per uv tool install installierbaren Paket machen · Dauer: ca. 90 min · Voraussetzung: Tag 4

Briefing

  • pyproject.toml ist die einzige Quelle für Name, Version, Abhängigkeiten und Tool-Konfiguration.
  • Qualität läuft automatisch: ruff (Lint, Format, Security-Regeln), mypy --strict, pytest mit Coverage-Schwelle.
  • pre-commit blockt fehlerhafte Commits, bevor sie das Repo erreichen.
  • uv build erzeugt Wheel und sdist, uv tool install macht daraus ein Kommando im PATH – isoliert in einem eigenen venv.
src/ + pyproject.toml --uv build--> dist/checkcert-0.2.0-py3-none-any.whl
        |                                  |
   pre-commit: ruff, mypy          uv tool install --> ~/.local/bin/checkcert

Drill 1: Kopie von Tag 4 mit eigenem Git-Repo

cd ~/py-lab
rsync -a --exclude .venv --exclude .git --exclude __pycache__ \
  --exclude '.*_cache' tag04-checkcert/ tag05-checkcert/
cd tag05-checkcert && git init -q
cat > .gitignore <<'EOF'
.venv/
__pycache__/
.*_cache/
.coverage
dist/
EOF
uv run pytest -q | tail -1

Erwartet:

21 passed, 1 skipped in 0.64s

Warum? Tag 4 bleibt als Referenz unangetastet. Das eigene Git-Repo brauchen wir für pre-commit und Release-Tags; .venv wird nicht kopiert, sondern von uv run neu angelegt.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Metadaten und Tool-Konfiguration

Wir schreiben pyproject.toml einmal komplett und ordentlich:

cat > pyproject.toml <<'EOF'
[project]
name = "checkcert"
version = "0.1.0"
description = "TLS-Zertifikate prüfen: Restlaufzeit in Tagen, Exit-Code nach Nagios"
readme = "README.md"
license = "MIT"
authors = [{ name = "Thomas Zachmann", email = "[email protected]" }]
keywords = ["tls", "x509", "certificate", "monitoring", "nagios"]
classifiers = [
    "Environment :: Console",
    "Programming Language :: Python :: 3.14",
    "Topic :: System :: Monitoring",
]
requires-python = ">=3.14"
dependencies = ["typer>=0.27.3"]

[project.scripts]
checkcert = "checkcert:main"

[build-system]
requires = ["uv_build>=0.9.26,<0.10.0"]
build-backend = "uv_build"

[dependency-groups]
dev = [
    "pytest>=9.1.1",
    "pytest-cov>=7.1.0",
    "ruff>=0.17.0",
]

[tool.ruff.lint]
extend-select = ["E501", "B", "UP", "SIM", "I", "S"]

[tool.ruff.lint.per-file-ignores]
"tests/*" = ["S101"]  # assert ist in pytest erwünscht

[tool.mypy]
strict = true
files = ["src"]

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "--cov=checkcert --cov-fail-under=85"
EOF
uv add -q --dev mypy
cat > README.md <<'EOF'
# checkcert

Prüft die Restlaufzeit von TLS-Zertifikaten und endet mit einem Exit-Code
nach Nagios-Konvention (0 OK, 1 WARN, 2 CRIT, 3 ERROR).

    checkcert github.com example.com:443 --warn 30 --crit 7
    checkcert -f hosts.txt
EOF

Warum? license = "MIT" ist ein SPDX-Ausdruck (PEP 639), Classifier und Keywords machen das Paket auffindbar. authors stammt bei uv init aus deiner git-Konfiguration – kontrolliere es. Die README landet als Beschreibung im Paket. Neu sind die Regeln I (Import-Sortierung) und S (Security, Bandit-Regeln), mypy im Strict-Modus sowie addopts: Jeder pytest-Lauf misst jetzt Coverage und scheitert unter 85 %.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Eine Quelle für die Version

Die Version steht nur in pyproject.toml; zur Laufzeit liest importlib.metadata sie aus dem installierten Paket.

cat > src/checkcert/__init__.py <<'EOF'
"""checkcert – TLS-Zertifikate prüfen."""

from importlib.metadata import version

from checkcert.cli import app

__version__ = version("checkcert")  # einzige Quelle: pyproject.toml


def main() -> None:
    app()
EOF

src/checkcert/cli.py bekommt eine Callback-Funktion show_version und einen letzten Parameter _version; der Rest ist unverändert aus Tag 4:

cat > src/checkcert/cli.py <<'EOF'
"""checkcert – Restlaufzeit von TLS-Zertifikaten prüfen (Exit-Code nach Nagios)."""

import logging
from importlib.metadata import version
from pathlib import Path
from typing import Annotated

import typer

from checkcert.core import Result, Status, check

app = typer.Typer(help=__doc__, add_completion=False)


def parse_target(target: str) -> tuple[str, int]:
    """'host' oder 'host:port' -> (host, port)."""
    host, sep, port = target.rpartition(":")
    if not sep:
        return target, 443
    if not port.isdigit():
        raise typer.BadParameter(f"ungültiger Port in {target!r}")
    return host, int(port)


def read_targets(path: Path) -> list[str]:
    """Eine Adresse pro Zeile; Leerzeilen und #-Kommentare werden ignoriert."""
    lines = path.read_text(encoding="utf-8").splitlines()
    return [s for line in lines if (s := line.split("#", 1)[0].strip())]


def render(r: Result) -> str:
    days = "-" if r.days is None else str(r.days)
    expires = f"{r.expires:%Y-%m-%d}" if r.expires else "-"
    line = f"{r.status.name:<6} {days:>5}  {expires:<10}  {r.host}:{r.port}"
    return f"{line}  ({r.error})" if r.error else line


def show_version(value: bool) -> None:
    if value:
        typer.echo(f"checkcert {version('checkcert')}")
        raise typer.Exit()


@app.command()
def main(
    targets: Annotated[list[str] | None, typer.Argument(help="host[:port]")] = None,
    file: Annotated[
        Path | None, typer.Option("--file", "-f", exists=True, help="Hostliste")
    ] = None,
    warn: Annotated[int, typer.Option(help="WARN unter so vielen Tagen")] = 30,
    crit: Annotated[int, typer.Option(help="CRIT unter so vielen Tagen")] = 7,
    timeout: Annotated[float, typer.Option(help="Sekunden pro Host")] = 5.0,
    verbose: Annotated[bool, typer.Option("--verbose", "-v")] = False,
    _version: Annotated[
        bool, typer.Option("--version", callback=show_version, is_eager=True)
    ] = False,
) -> None:
    """Prüft alle Ziele und endet mit dem schlechtesten Status als Exit-Code."""
    logging.basicConfig(
        level=logging.DEBUG if verbose else logging.ERROR,
        format="%(levelname)s %(name)s: %(message)s",
    )
    all_targets = (targets or []) + (read_targets(file) if file else [])
    if not all_targets:
        raise typer.BadParameter("mindestens ein Host oder --file angeben")
    pairs = [parse_target(t) for t in all_targets]  # Fehler vor dem ersten Check
    typer.echo(f"{'STATUS':<6} {'TAGE':>5}  {'ABLAUF':<10}  HOST")
    worst = Status.OK
    for host, port in pairs:
        result = check(host, port, warn=warn, crit=crit, timeout=timeout)
        typer.echo(render(result))
        worst = max(worst, result.status)
    raise typer.Exit(code=int(worst))
EOF

Test an tests/test_cli.py anhängen:

cat >> tests/test_cli.py <<'EOF'


def test_version_flag() -> None:
    result = CliRunner().invoke(cli.app, ["--version"])
    assert result.exit_code == 0
    assert result.stdout.startswith("checkcert 0.")
EOF
uv run checkcert --version
uv run python -m checkcert --version

Erwartet:

checkcert 0.1.0
checkcert 0.1.0

Warum? is_eager=True wertet --version vor allen anderen Argumenten aus – sonst würde typer erst „mindestens ein Host” bemängeln. Eine zweite, von Hand gepflegte Versionsnummer im Code veraltet garantiert irgendwann.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Lint, Format, Typen, Tests

uv run ruff check . && uv run ruff format --check .
uv run mypy
uv run pytest -q | tail -2

Erwartet (gekürzt):

All checks passed!
8 files already formatted
Success: no issues found in 4 source files
Required test coverage of 85% reached. Total coverage: 91.92%
22 passed, 1 skipped in 0.11s

Warum? mypy liest files und strict aus pyproject.toml, deshalb reicht uv run mypy. Als Dev-Abhängigkeit ist die Version im uv.lock gepinnt – lokal, im CI und im Hook prüft dieselbe mypy-Version. Die S-Regeln finden z. B. subprocess mit shell=True, hart kodierte Passwörter oder assert im Produktivcode.

Fortschritt speichern? Kostenlos registrieren

Drill 5: pre-commit als Türsteher

Lokale Hooks rufen die Tools über uv run auf, also exakt die Versionen aus uv.lock:

cat > .pre-commit-config.yaml <<'EOF'
# Lokale Hooks: nutzen die Versionen aus uv.lock, kein zweites Tool-Pinning
repos:
  - repo: local
    hooks:
      - id: ruff-check
        name: ruff check
        entry: uv run ruff check --fix
        language: system
        types: [python]
      - id: ruff-format
        name: ruff format
        entry: uv run ruff format
        language: system
        types: [python]
      - id: mypy
        name: mypy
        entry: uv run mypy
        language: system
        types: [python]
        pass_filenames: false
EOF
uvx pre-commit install
git add -A && uvx pre-commit run --all-files
git commit -qm "checkcert 0.1.0 als Paket" && git log --oneline

Erwartet (Hash weicht ab):

pre-commit installed at .git/hooks/pre-commit
ruff check...............................................................Passed
ruff format..............................................................Passed
mypy.....................................................................Passed
ruff check...............................................................Passed
ruff format..............................................................Passed
mypy.....................................................................Passed
41f7af0 checkcert 0.1.0 als Paket

Die Hooks laufen zweimal: einmal per run --all-files (prüft alle Dateien, die Git kennt – deshalb vorher git add), einmal automatisch beim Commit. Jetzt ein Typfehler – days kann None sein:

cat >> src/checkcert/core.py <<'EOF'


def days_left(r: Result) -> int:
    return r.days
EOF
git add -A && git commit -qm "days_left"; echo "exit=$?"
git restore --staged --worktree src/checkcert/core.py

Erwartet (gekürzt):

mypy.....................................................................Failed
- hook id: mypy
- exit code: 1

src/checkcert/core.py:95: error: Incompatible return value type (got "int | None...
exit=1

Der Commit ist nicht passiert. uvx führt pre-commit aus dem uv-Cache aus – keine globale Installation.

Tipp: Im Notfall umgeht git commit --no-verify die Hooks. Das CI muss deshalb dieselben Prüfungen noch einmal laufen lassen (Tag 14).

Fortschritt speichern? Kostenlos registrieren

Drill 6: Versionieren

Semantic Versioning: MAJOR.MINOR.PATCH. Neues Feature (--version) ohne Bruch heißt Minor-Release.

uv version
uv version --bump minor --dry-run
uv version --bump minor
git commit -qam "Release 0.2.0" && git tag v0.2.0
uv run checkcert --version

Erwartet (gekürzt):

checkcert 0.1.0
checkcert 0.1.0 => 0.2.0
checkcert 0.1.0 => 0.2.0
ruff check...........................................(no files to check)Skipped
ruff format..........................................(no files to check)Skipped
mypy.................................................(no files to check)Skipped
checkcert 0.2.0

Warum? uv version --bump ändert pyproject.toml, aktualisiert uv.lock und installiert das Projekt neu – deshalb meldet --version sofort 0.2.0. Der Git-Tag markiert den Stand, aus dem das Release gebaut wird. Die Hooks überspringen sich, weil keine Python-Datei geändert wurde.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Bauen und hineinschauen

uv build
unzip -l dist/checkcert-0.2.0-py3-none-any.whl | awk 'NR>3 {print $4}' | grep .
unzip -p dist/checkcert-0.2.0-py3-none-any.whl \
  checkcert-0.2.0.dist-info/entry_points.txt

Erwartet (gekürzt):

Successfully built dist/checkcert-0.2.0.tar.gz
Successfully built dist/checkcert-0.2.0-py3-none-any.whl
checkcert/
checkcert/__init__.py
checkcert/__main__.py
checkcert/cli.py
checkcert/core.py
checkcert-0.2.0.dist-info/
checkcert-0.2.0.dist-info/WHEEL
checkcert-0.2.0.dist-info/entry_points.txt
checkcert-0.2.0.dist-info/METADATA
checkcert-0.2.0.dist-info/RECORD
[console_scripts]
checkcert = checkcert:main

Warum? Das Wheel ist ein ZIP mit genau dem Paket und Metadaten – keine Tests, kein lab/, kein venv. py3-none-any heißt: reines Python, läuft auf jeder Plattform. Das sdist (.tar.gz) enthält die Quellen für Umgebungen, die selbst bauen wollen. entry_points.txt wird bei der Installation zum ausführbaren checkcert.

Fortschritt speichern? Kostenlos registrieren

Drill 8: Das Tool ist fertig

uv tool install dist/checkcert-0.2.0-py3-none-any.whl
uv tool list
cd / && command -v checkcert && checkcert --version
checkcert github.com expired.badssl.com --timeout 3; echo "exit=$?"
cd ~/py-lab/tag05-checkcert

Erwartet (Pfad und Tage weichen ab):

Installed 1 executable: checkcert
checkcert v0.2.0
- checkcert
/Users/<du>/.local/bin/checkcert
checkcert 0.2.0
STATUS  TAGE  ABLAUF      HOST
OK        50  2026-11-29  github.com:443
ERROR      -  -           expired.badssl.com:443  (certificate has expired)
exit=3

checkcert läuft jetzt aus jedem Verzeichnis, in einem eigenen venv unter ~/.local/share/uv/tools/ – ohne das System-Python oder andere Tools zu berühren. Für ein Update: neue Version bauen, dann uv tool install --force dist/<neues-wheel>. Während der Entwicklung ist uv tool install --editable . praktisch: Codeänderungen wirken sofort.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

#!/usr/bin/env bash
check() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"; else echo "✘ $1"; fi; }
cd ~/py-lab/tag05-checkcert
check "Tests grün, Coverage >= 85 %" "uv run pytest -q"
check "ruff sauber" "uv run ruff check . && uv run ruff format --check ."
check "mypy strict" "uv run mypy"
check "pre-commit-Hook aktiv" "test -x .git/hooks/pre-commit"
check "Release getaggt" "git tag | grep -qx v0.2.0"
check "Wheel ohne Tests" \
  "! unzip -l dist/checkcert-0.2.0-py3-none-any.whl | grep -q tests/"
check "checkcert 0.2.0 im PATH" "checkcert --version | grep -qx 'checkcert 0.2.0'"

Erwartet:

✔ Tests grün, Coverage >= 85 %
✔ ruff sauber
✔ mypy strict
✔ pre-commit-Hook aktiv
✔ Release getaggt
✔ Wheel ohne Tests
✔ checkcert 0.2.0 im PATH

Challenge

Die Tests dauern Sekundenbruchteile, sollen aber nicht jeden Commit bremsen, sobald die Suite wächst. Lass pytest nur vor git push laufen.

Hinweis: pre-commit kennt stages: [pre-push]; den passenden Git-Hook installiert --hook-type pre-push.

Lösung

An .pre-commit-config.yaml anhängen (Einrückung wie die anderen Hooks):

      - id: pytest
        name: pytest
        entry: uv run pytest -q
        language: system
        pass_filenames: false
        always_run: true
        stages: [pre-push]
uvx pre-commit install --hook-type pre-push
uvx pre-commit run --hook-stage pre-push --all-files
ls .git/hooks | grep -v sample

Erwartet:

pre-commit installed at .git/hooks/pre-push
ruff check...............................................................Passed
ruff format..............................................................Passed
mypy.....................................................................Passed
pytest...................................................................Passed
pre-commit
pre-push

Hooks ohne stages laufen in jeder Stufe; always_run: true startet pytest auch, wenn keine Python-Datei im Push steckt.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Interne Pakete in eine eigene Registry (Artifactory, Nexus, GitLab Package Registry) mit uv publish --publish-url ... hochladen; installieren per --index – nie Paketnamen nutzen, die es auch auf PyPI gibt (Dependency Confusion).
  • Releases nur aus dem CI bauen, nicht vom Laptop: sauberer Checkout, Tag als Auslöser, Wheel signieren (Sigstore) und eine SBOM erzeugen.
  • Air-Gap: uv tool install aus einem Wheelhouse (--find-links ./wheels --offline), Abhängigkeiten vorher mit uv export und pip download einsammeln.
  • Lizenz ernst nehmen: Firmencode nicht versehentlich mit license = "MIT" veröffentlichen; Lizenzen der Abhängigkeiten prüfen, z. B. uv run --with pip-licenses pip-licenses.
  • --no-verify ist erlaubt, Pflichtprüfungen gehören deshalb zusätzlich als Required Check in den Merge Request.