Tag 5: Packaging und Qualität – checkcert als Paket
Ziel:
checkcertaus Tag 4 zu einem versionierten, geprüften und peruv tool installinstallierbaren Paket machen · Dauer: ca. 90 min · Voraussetzung: Tag 4
Briefing
pyproject.tomlist 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 builderzeugt Wheel und sdist,uv tool installmacht 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 -1Erwartet:
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
EOFWarum? 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()
EOFsrc/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))
EOFTest 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 --versionErwartet:
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 -2Erwartet (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 --onelineErwartet (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.pyErwartet (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-verifydie 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 --versionErwartet (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.txtErwartet (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-checkcertErwartet (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 sampleErwartet:
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 installaus einem Wheelhouse (--find-links ./wheels --offline), Abhängigkeiten vorher mituv exportundpip downloadeinsammeln. - 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-verifyist erlaubt, Pflichtprüfungen gehören deshalb zusätzlich als Required Check in den Merge Request.