Tag 3: CLI-Tools mit typer – tidy
Ziel: Ein CLI
tidymit 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"]
EOFErwartet (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/downloadsErwartet:
.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"))))
EOFErwartet:
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
EOFplan()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.tomllibist seit 3.11 in der Standardbibliothek (nur lesen). Es braucht die Datei im Binärmodus"rb".rules.get(full) or rules.get(last):orliefert 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 einenPathund prüftexists=Trueundfile_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_cmdheißt per@app.command("plan")trotzdemplanund kollidiert nicht mit der importierten Funktion). typer.echo(..., err=True)schreibt nachstderr.
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 | sortErwartet:
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 dushutil.move().
Fortschritt speichern? Kostenlos registrieren
Drill 5: subprocess – Systembefehle sicher aufrufen
uv run tidy du lab/downloadsErwartet (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=Truemit zusammengebauten Strings ist Command Injection mit Ansage. check=True: Exit-Code ungleich 0 wird zur ExceptionCalledProcessError– kein stilles Weiterlaufen wie in Bash ohneset -e.capture_output=True, text=True:stdout/stderrlanden alsstrim Ergebnis statt im Terminal.raise ... from errhä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)
EOFErwartet:
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.tomlErwartet:
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 srcErwartet:
...... [100%]
6 passed in 0.02s
All checks passed!
6 files already formatted
Success: no issues found in 4 source files
tmp_pathist 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.invokestartet das CLI im selben Prozess und liefertexit_codeundoutput– schneller und genauer alssubprocessim Test.- Hier
uv run --with mypystattuvx 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/downloadsErwartet (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 ~/Downloadslesen, dann entscheiden. Ab Tag 5 installierst du solche Tools mituv tool installglobal.
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.shErwartet:
✔ 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 errIn 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 == 2printf '[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 -qErwartet:
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
--yesfür Automatisierung, und ein Protokoll (welche Datei wohin), damit ein Undo möglich ist. subprocessnie mitshell=Trueund 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()undis_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.