Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 3: CLI-Tools mit typer – tidy

Ziel: Ein CLI tidy mit typer, pathlib und subprocess bauen, das einen Download-Ordner nach Regeln aufräumt – standardmäßig als Dry-Run, mit sauberen Exit-Codes · Dauer: ca. 120 min · Voraussetzung: Tag 2

Briefing

  • typer baut aus Funktionen mit Typ-Hints ein CLI: Argumente, Optionen, Hilfe, Validierung und Unterbefehle.
  • pathlib ersetzt os.path: Path("a") / "b", .suffix, .iterdir(), .move() (neu in 3.14).
  • subprocess.run ruft Systembefehle sicher auf: Argumentliste statt Shell-String, check=True, capture_output=True.
  • Zerstörerische Tools zeigen erst den Plan. Ausgeführt wird nur mit apply, nach Rückfrage oder mit --yes.
tidy plan  DIR ──► rules.plan() ──► [Move(src, dst), ...] ──► Ausgabe (Dry-Run)
tidy apply DIR ──► rules.plan() ──► confirm ──► Path.move() ──► Exit 0 | 1 (Konflikte)
tidy du    DIR ──► subprocess.run(["du", "-sk", ...])

Drill 1: Projekt und Übungsordner

cd ~/py-lab
uv init -q --package --name tidy tag03-tidy
cd tag03-tidy
uv add typer
uv add -q --dev pytest ruff
cat >> pyproject.toml <<'EOF'

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

Erwartet (gekürzt):

 + rich==15.0.0
 + typer==0.27.3

Sicherheit: Du übst an lab/downloads, nie direkt an ~/Downloads. Ein Skript baut den Übungsordner jederzeit neu auf.

mkdir -p lab
cat > lab/reset.sh <<'EOF'
#!/usr/bin/env bash
# Baut den Übungsordner lab/downloads neu auf – nur Lab-Dateien.
set -euo pipefail
cd "$(dirname "$0")"
rm -rf downloads
mkdir -p downloads/alter-ordner
cd downloads
touch rechnung-2026-09.pdf notizen.txt setup.dmg backup.tar.gz logs.gz \
  screenshot.png "Mein Lebenslauf.docx" .DS_Store
head -c 300000 /dev/zero > urlaub.JPG
EOF
bash lab/reset.sh
ls -A lab/downloads

Erwartet:

.DS_Store
alter-ordner
backup.tar.gz
logs.gz
Mein Lebenslauf.docx
notizen.txt
rechnung-2026-09.pdf
screenshot.png
setup.dmg
urlaub.JPG

Fortschritt speichern? Kostenlos registrieren

Drill 2: pathlib und die Regeln

uv run python - <<'EOF'
from pathlib import Path

p = Path("lab/downloads") / "backup.tar.gz"
print(p.name, p.stem, p.suffix, p.suffixes)
print(p.parent, p.exists(), p.is_file())
print(p.with_name("neu.zip"))
print(sorted(x.name for x in p.parent.iterdir() if x.is_dir()))
print(len(list(p.parent.glob("*.pdf"))))
EOF

Erwartet:

backup.tar.gz backup.tar .gz ['.tar', '.gz']
lab/downloads True True
lab/downloads/neu.zip
['alter-ordner']
1

/ verbindet Pfade plattformunabhängig, suffixes kennt Doppelendungen wie .tar.gz. Die Regel-Logik kommt in ein eigenes Modul, ganz ohne CLI-Code – so ist sie leicht testbar:

cat > src/tidy/rules.py <<'EOF'
"""Regeln laden und einen Umzugsplan berechnen – ohne etwas anzufassen."""

import tomllib
from dataclasses import dataclass
from pathlib import Path

DEFAULT_RULES = {
    "pdf": "Dokumente",
    "docx": "Dokumente",
    "txt": "Dokumente",
    "jpg": "Bilder",
    "png": "Bilder",
    "dmg": "Installer",
    "zip": "Archive",
    "tar.gz": "Archive",
}


@dataclass(frozen=True)
class Move:
    src: Path
    dst: Path

    @property
    def conflict(self) -> bool:
        return self.dst.exists()


def load_rules(path: Path | None) -> dict[str, str]:
    """Regeln aus einer TOML-Datei ([rules] endung = "Ordner") oder Defaults."""
    if path is None:
        return DEFAULT_RULES
    with path.open("rb") as f:
        data = tomllib.load(f)
    return {ext.lower().lstrip("."): folder for ext, folder in data["rules"].items()}


def target_folder(file: Path, rules: dict[str, str]) -> str | None:
    """Erst die volle Endung (tar.gz), dann die letzte (gz) nachschlagen."""
    full = "".join(file.suffixes).lower().lstrip(".")
    last = file.suffix.lower().lstrip(".")
    return rules.get(full) or rules.get(last)


def plan(directory: Path, rules: dict[str, str]) -> list[Move]:
    """Ein Move pro Datei mit bekannter Endung; Ordner und dotfiles bleiben."""
    moves = []
    for file in sorted(directory.iterdir()):
        if not file.is_file() or file.name.startswith("."):
            continue
        folder = target_folder(file, rules)
        if folder is not None:
            moves.append(Move(file, directory / folder / file.name))
    return moves
EOF
  • plan() ist eine reine Funktion: Sie liest das Verzeichnis, verändert aber nichts. Dry-Run und Ausführung nutzen denselben Plan – was du siehst, passiert auch.
  • tomllib ist seit 3.11 in der Standardbibliothek (nur lesen). Es braucht die Datei im Binärmodus "rb".
  • rules.get(full) or rules.get(last): or liefert den ersten „wahren” Wert – ein kompakter Fallback.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Die typer-App

cat > src/tidy/cli.py <<'EOF'
"""tidy – einen Download-Ordner nach Regeln aufräumen (Standard: Dry-Run)."""

import subprocess
from pathlib import Path
from typing import Annotated

import typer

from tidy.rules import load_rules, plan

app = typer.Typer(help=__doc__, no_args_is_help=True)

DirArg = Annotated[
    Path, typer.Argument(exists=True, file_okay=False, help="Ordner zum Aufräumen")
]
RulesOpt = Annotated[
    Path | None, typer.Option("--rules", "-r", exists=True, help="TOML-Regeldatei")
]


@app.command("plan")
def plan_cmd(directory: DirArg, rules: RulesOpt = None) -> None:
    """Zeigt, was verschoben würde. Ändert nichts."""
    moves = plan(directory, load_rules(rules))
    for m in moves:
        mark = "!" if m.conflict else " "
        typer.echo(f"{mark} {m.src.name:<28} -> {m.dst.parent.name}/")
    conflicts = sum(m.conflict for m in moves)
    typer.echo(f"{len(moves)} Dateien, {conflicts} Konflikte (Dry-Run)")


@app.command()
def apply(
    directory: DirArg,
    rules: RulesOpt = None,
    yes: Annotated[bool, typer.Option("--yes", "-y", help="ohne Rückfrage")] = False,
) -> None:
    """Verschiebt die Dateien. Exit 1, wenn es Konflikte gab."""
    moves = plan(directory, load_rules(rules))
    if not moves:
        typer.echo("Nichts zu tun.")
        return
    if not yes:
        typer.confirm(f"{len(moves)} Dateien verschieben?", abort=True)
    conflicts = 0
    for m in moves:
        if m.conflict:
            typer.echo(f"Konflikt, übersprungen: {m.dst}", err=True)
            conflicts += 1
            continue
        m.dst.parent.mkdir(exist_ok=True)
        m.src.move(m.dst)
        typer.echo(f"verschoben: {m.src.name} -> {m.dst.parent.name}/")
    if conflicts:
        raise typer.Exit(code=1)


@app.command()
def du(directory: DirArg) -> None:
    """Größe der Unterordner über das Systemkommando du."""
    folders = sorted(str(p) for p in directory.iterdir() if p.is_dir())
    if not folders:
        typer.echo("Keine Unterordner.")
        return
    try:
        result = subprocess.run(
            ["du", "-sk", *folders], capture_output=True, text=True, check=True
        )
    except subprocess.CalledProcessError as err:
        typer.echo(f"du fehlgeschlagen ({err.returncode}): {err.stderr}", err=True)
        raise typer.Exit(code=3) from err
    for line in result.stdout.splitlines():
        kb, path = line.split("\t", 1)
        typer.echo(f"{int(kb):>8} KB  {Path(path).name}/")
EOF
cat > src/tidy/__init__.py <<'EOF'
"""tidy – Ordner nach Regeln aufräumen."""

from tidy.cli import app


def main() -> None:
    app()
EOF
cat > src/tidy/__main__.py <<'EOF'
from tidy import main

main()
EOF
uv run tidy plan lab/downloads; echo "exit=$?"

Erwartet:

  Mein Lebenslauf.docx         -> Dokumente/
  backup.tar.gz                -> Archive/
  notizen.txt                  -> Dokumente/
  rechnung-2026-09.pdf         -> Dokumente/
  screenshot.png               -> Bilder/
  setup.dmg                    -> Installer/
  urlaub.JPG                   -> Bilder/
7 Dateien, 0 Konflikte (Dry-Run)
exit=0

logs.gz, .DS_Store und alter-ordner bleiben liegen: keine Regel, dotfile, Ordner.

  • Annotated[Path, typer.Argument(...)] trennt Typ und CLI-Metadaten. typer wandelt den String in einen Path und prüft exists=True und file_okay=False, bevor dein Code läuft.
  • Wiederkehrende Parameter als Typ-Alias (DirArg, RulesOpt) halten die Befehle schlank.
  • Der Docstring wird zur Hilfe des Befehls, der Funktionsname zum Befehlsnamen (plan_cmd heißt per @app.command("plan") trotzdem plan und kollidiert nicht mit der importierten Funktion).
  • typer.echo(..., err=True) schreibt nach stderr.
uv run tidy plan gibt-es-nicht; echo "exit=$?"

Erwartet:

Usage: tidy plan [OPTIONS] {directory}
Try 'tidy plan --help' for help.
╭─ Error ──────────────────────────────────────────────────────────────────────╮
│ Invalid value for 'directory': Directory 'gibt-es-nicht' does not exist.     │
╰──────────────────────────────────────────────────────────────────────────────╯
exit=2

Fortschritt speichern? Kostenlos registrieren

Drill 4: Ausführen mit Rückfrage und Exit-Codes

Lege einen Konflikt an: Im Ziel liegt schon eine notizen.txt.

mkdir -p lab/downloads/Dokumente
echo alt > lab/downloads/Dokumente/notizen.txt
uv run tidy plan lab/downloads | head -4
echo n | uv run tidy apply lab/downloads; echo "exit=$?"

Erwartet:

  Mein Lebenslauf.docx         -> Dokumente/
  backup.tar.gz                -> Archive/
! notizen.txt                  -> Dokumente/
  rechnung-2026-09.pdf         -> Dokumente/
7 Dateien verschieben? [y/N]: Aborted.
exit=1

Mit echo n beantwortest du die Rückfrage aus der Pipe. Jetzt ernsthaft:

uv run tidy apply lab/downloads --yes; echo "exit=$?"
find lab/downloads -type f | sort

Erwartet:

verschoben: Mein Lebenslauf.docx -> Dokumente/
verschoben: backup.tar.gz -> Archive/
Konflikt, übersprungen: lab/downloads/Dokumente/notizen.txt
verschoben: rechnung-2026-09.pdf -> Dokumente/
verschoben: screenshot.png -> Bilder/
verschoben: setup.dmg -> Installer/
verschoben: urlaub.JPG -> Bilder/
exit=1
lab/downloads/.DS_Store
lab/downloads/Archive/backup.tar.gz
lab/downloads/Bilder/screenshot.png
lab/downloads/Bilder/urlaub.JPG
lab/downloads/Dokumente/Mein Lebenslauf.docx
lab/downloads/Dokumente/notizen.txt
lab/downloads/Dokumente/rechnung-2026-09.pdf
lab/downloads/Installer/setup.dmg
lab/downloads/logs.gz
lab/downloads/notizen.txt
Exit-Code Bedeutung bei tidy
0 alles erledigt oder nichts zu tun
1 Konflikte übersprungen oder abgebrochen
2 falsche Bedienung (typer/click)
3 Systembefehl fehlgeschlagen

Warum nicht überschreiben? Ein Aufräum-Tool, das still Daten ersetzt, ist ein Datenverlust-Tool. Konflikte überspringen, melden und per Exit-Code signalisieren – dann kann ein Cronjob oder Skript reagieren.

Tipp: Path.move() ist neu in Python 3.14 und funktioniert auch über Dateisystemgrenzen. Auf älteren Versionen nimmst du shutil.move().

Fortschritt speichern? Kostenlos registrieren

Drill 5: subprocess – Systembefehle sicher aufrufen

uv run tidy du lab/downloads

Erwartet (Größen können je nach Dateisystem abweichen):

       0 KB  Archive/
     296 KB  Bilder/
       4 KB  Dokumente/
       0 KB  Installer/
       0 KB  alter-ordner/

Die Regeln für subprocess.run:

  • Liste statt String: ["du", "-sk", *folders] übergibt jeden Pfad als eigenes Argument. Leerzeichen oder ; rm -rf ~ in Dateinamen bleiben harmlos. shell=True mit zusammengebauten Strings ist Command Injection mit Ansage.
  • check=True: Exit-Code ungleich 0 wird zur Exception CalledProcessError – kein stilles Weiterlaufen wie in Bash ohne set -e.
  • capture_output=True, text=True: stdout/stderr landen als str im Ergebnis statt im Terminal.
  • raise ... from err hängt die Ursache an; im Traceback siehst du beide Fehler.
uv run python - <<'EOF'
import subprocess

r = subprocess.run(["ls", "/gibt-es-nicht"], capture_output=True, text=True)
print(r.returncode, r.stderr.strip())
try:
    subprocess.run(["false"], check=True)
except subprocess.CalledProcessError as err:
    print("CalledProcessError, returncode", err.returncode)
EOF

Erwartet:

1 ls: /gibt-es-nicht: No such file or directory
CalledProcessError, returncode 1

Fortschritt speichern? Kostenlos registrieren

Drill 6: Eigene Regeln per TOML

bash lab/reset.sh
cat > lab/tidy.toml <<'EOF'
[rules]
pdf = "Belege"
".GZ" = "Archive"
dmg = "Installer"
EOF
uv run tidy plan lab/downloads --rules lab/tidy.toml

Erwartet:

  backup.tar.gz                -> Archive/
  logs.gz                      -> Archive/
  rechnung-2026-09.pdf         -> Belege/
  setup.dmg                    -> Installer/
4 Dateien, 0 Konflikte (Dry-Run)

load_rules normalisiert die Schlüssel (".GZ" wird zu gz), und backup.tar.gz fällt mangels tar.gz-Regel auf gz zurück. Eigene Regeln ersetzen die Defaults komplett – PNG und TXT bleiben diesmal liegen.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Tests mit tmp_path und CliRunner

mkdir -p tests
cat > tests/test_tidy.py <<'EOF'
from pathlib import Path

from typer.testing import CliRunner

from tidy.cli import app
from tidy.rules import DEFAULT_RULES, load_rules, plan, target_folder

runner = CliRunner()


def make_files(directory: Path, *names: str) -> None:
    for name in names:
        (directory / name).touch()


def test_target_folder():
    assert target_folder(Path("A.PDF"), DEFAULT_RULES) == "Dokumente"
    assert target_folder(Path("b.tar.gz"), DEFAULT_RULES) == "Archive"
    assert target_folder(Path("c.md"), DEFAULT_RULES) is None


def test_plan_ignoriert_ordner_und_dotfiles(tmp_path):
    make_files(tmp_path, "a.pdf", ".DS_Store", "x.unbekannt")
    (tmp_path / "sub.pdf").mkdir()
    moves = plan(tmp_path, DEFAULT_RULES)
    assert [m.dst for m in moves] == [tmp_path / "Dokumente" / "a.pdf"]


def test_load_rules_aus_toml(tmp_path):
    rules = tmp_path / "r.toml"
    rules.write_text('[rules]\n".PDF" = "Belege"\n', encoding="utf-8")
    assert load_rules(rules) == {"pdf": "Belege"}


def test_plan_cmd_aendert_nichts(tmp_path):
    make_files(tmp_path, "a.pdf")
    result = runner.invoke(app, ["plan", str(tmp_path)])
    assert result.exit_code == 0
    assert "1 Dateien, 0 Konflikte" in result.output
    assert (tmp_path / "a.pdf").exists()


def test_apply_verschiebt(tmp_path):
    make_files(tmp_path, "a.pdf", "b.png")
    result = runner.invoke(app, ["apply", str(tmp_path), "--yes"])
    assert result.exit_code == 0
    assert (tmp_path / "Dokumente" / "a.pdf").exists()
    assert (tmp_path / "Bilder" / "b.png").exists()


def test_apply_konflikt_gibt_exit_1(tmp_path):
    make_files(tmp_path, "a.pdf")
    (tmp_path / "Dokumente").mkdir()
    (tmp_path / "Dokumente" / "a.pdf").write_text("alt", encoding="utf-8")
    result = runner.invoke(app, ["apply", str(tmp_path), "-y"])
    assert result.exit_code == 1
    assert (tmp_path / "a.pdf").exists()
EOF
uv run pytest -q
uv run ruff check && uv run ruff format --check
uv run --with mypy mypy --strict src

Erwartet:

......                                                                   [100%]
6 passed in 0.02s
All checks passed!
6 files already formatted
Success: no issues found in 4 source files
  • tmp_path ist eine pytest-Fixture: ein frischer, leerer Ordner pro Test, der nach dem Lauf aufgeräumt wird. Tests fassen so nie echte Dateien an (mehr an Tag 4).
  • CliRunner.invoke startet das CLI im selben Prozess und liefert exit_code und output – schneller und genauer als subprocess im Test.
  • Hier uv run --with mypy statt uvx mypy: mypy muss typer sehen, sonst gelten alle Dekoratoren als untypisiert.

Fortschritt speichern? Kostenlos registrieren

Drill 8: Das Tool ist fertig

bash lab/reset.sh
uv run tidy --help
uv run tidy apply lab/downloads -y > /dev/null; echo "exit=$?"
uv run tidy apply lab/downloads -y; echo "exit=$?"
uv run python -m tidy plan lab/downloads

Erwartet (gekürzt):

 Usage: tidy [OPTIONS] COMMAND [ARGS]...

 tidy – einen Download-Ordner nach Regeln aufräumen (Standard: Dry-Run).

╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ plan   Zeigt, was verschoben würde. Ändert nichts.                           │
│ apply  Verschiebt die Dateien. Exit 1, wenn es Konflikte gab.                │
│ du     Größe der Unterordner über das Systemkommando du.                     │
╰──────────────────────────────────────────────────────────────────────────────╯
exit=0
Nichts zu tun.
exit=0
0 Dateien, 0 Konflikte (Dry-Run)

Ein zweiter Lauf ändert nichts mehr: tidy ist idempotent. Das ist die Eigenschaft, die ein Tool cron- und CI-tauglich macht.

Tipp: Für den echten Ordner erst uv run tidy plan ~/Downloads lesen, dann entscheiden. Ab Tag 5 installierst du solche Tools mit uv tool install global.

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/tag03-tidy
bash lab/reset.sh
check "plan findet 7 Dateien" \
  "uv run tidy plan lab/downloads | grep -q '7 Dateien, 0 Konflikte'"
check "plan ändert nichts" "test -f lab/downloads/setup.dmg"
check "apply verschiebt" \
  "uv run tidy apply lab/downloads -y && test -f lab/downloads/Installer/setup.dmg"
check "zweiter Lauf idempotent" "uv run tidy apply lab/downloads -y | grep -q Nichts"
check "Konflikt gibt Exit 1" "bash lab/reset.sh && mkdir lab/downloads/Bilder && \
  touch lab/downloads/Bilder/screenshot.png && ! uv run tidy apply lab/downloads -y"
check "unbekannter Ordner gibt Exit 2" "uv run tidy plan /gibt/es/nicht; test \$? -eq 2"
check "du nutzt subprocess" "uv run tidy du lab/downloads | grep -q 'KB  Bilder/'"
check "Tests grün" "uv run pytest -q"
check "ruff sauber" "uv run ruff check && uv run ruff format --check"
bash lab/reset.sh

Erwartet:

✔ plan findet 7 Dateien
✔ plan ändert nichts
✔ apply verschiebt
✔ zweiter Lauf idempotent
✔ Konflikt gibt Exit 1
✔ unbekannter Ordner gibt Exit 2
✔ du nutzt subprocess
✔ Tests grün
✔ ruff sauber

Challenge

Eine kaputte Regeldatei ([regeln] statt [rules], rules = 42 oder ein TOML-Syntaxfehler) erzeugt heute einen langen Traceback. Mach daraus eine klare Meldung auf stderr und Exit-Code 2 – plus Test.

Hinweis: Fang die drei möglichen Exceptions in einer kleinen Funktion in cli.py ab und beende mit raise typer.Exit(code=2) from err.

Lösung

In src/tidy/cli.py oben import tomllib ergänzen, vor plan_cmd einfügen:

def get_rules(path: Path | None) -> dict[str, str]:
    """Regeln laden; kaputte Datei -> klare Meldung und Exit 2."""
    try:
        return load_rules(path)
    except (tomllib.TOMLDecodeError, KeyError, AttributeError) as err:
        typer.echo(f"Regeldatei ungültig: {err!r}", err=True)
        raise typer.Exit(code=2) from err

In plan_cmd und apply jeweils load_rules(rules) durch get_rules(rules) ersetzen. Test in tests/test_tidy.py anhängen:

def test_kaputte_regeln_geben_exit_2(tmp_path):
    rules = tmp_path / "r.toml"
    rules.write_text("[regeln]\n", encoding="utf-8")
    result = runner.invoke(app, ["plan", str(tmp_path), "--rules", str(rules)])
    assert result.exit_code == 2
printf '[regeln]\npdf = "x"\n' > lab/kaputt.toml
uv run tidy plan lab/downloads -r lab/kaputt.toml; echo "exit=$?"
printf 'rules = 42\n' > lab/kaputt.toml
uv run tidy plan lab/downloads -r lab/kaputt.toml; echo "exit=$?"
rm lab/kaputt.toml
uv run pytest -q

Erwartet:

Regeldatei ungültig: KeyError('rules')
exit=2
Regeldatei ungültig: AttributeError("'int' object has no attribute 'items'")
exit=2
.......                                                                  [100%]
7 passed in 0.02s

Warum Exit 2 und nicht 1? Eine kaputte Konfiguration ist ein Bedienfehler wie eine falsche Option – der Aufrufer muss etwas ändern, ein Retry hilft nicht.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Destruktive Tools: Dry-Run als Default, explizites --yes für Automatisierung, und ein Protokoll (welche Datei wohin), damit ein Undo möglich ist.
  • subprocess nie mit shell=True und Benutzereingaben; ruff erkennt das mit den Bandit-Regeln (S602, S603), die du an Tag 5 aktivierst.
  • Pfade aus Konfiguration gegen Ausbrüche prüfen (.., Symlinks): Path.resolve() und is_relative_to() vor jedem Schreiben.
  • Exit-Codes dokumentieren und stabil halten – Monitoring, cron und CI hängen daran.
  • typer erzeugt Shell-Completion (tidy --install-completion); für Teams lieber im Paket ausliefern als in Dotfiles basteln.