Ein Python-Kommandozeilenwerkzeug entwerfen: argparse, main() und Exit-Codes

Ziel

Ein Kommandozeilenwerkzeug bauen, das sich von Shellskripten, CI-Jobs und Agenten ansteuern lässt: vorhersagbare Argumente, ein Hilfetext, der zugleich die Dokumentation ist, strukturierte Exit-Codes und saubere Streams.

Voraussetzungen

Ein Paket mit einer pyproject.toml (siehe den Artikel zum Packaging), dessen Logik in importierbaren Funktionen liegt, getrennt von der Argumentverarbeitung.

Schritte

1. def main(argv: list[str] | None = None) -> int schreiben, das den Parser aufbaut, argv parst (mit Rückfall auf sys.argv[1:]) und einen Exit-Code zurückgibt. Als [project.scripts] tool = "pkg.cli:main" registrieren und if __name__ == "__main__": sys.exit(main()) ergänzen. Tests rufen dann main(["--flag", "x"]) auf und prüfen den Rückgabewert und die erfasste Ausgabe.
2. Den Parser mit prog, description und einem epilog mit Beispielen aufbauen. type=-Konverter verwenden (int, pathlib.Path oder eine Funktion, die ArgumentTypeError auslöst), damit ungültige Werte als Nutzungsfehler gemeldet werden, choices= für geschlossene Wertemengen und add_subparsers(dest="command", required=True) für Werkzeuge mit mehreren Unterbefehlen.
3. Der Konvention folgen, die die Dokumentation zu sys.exit beschreibt: Unix-Programme verwenden im Allgemeinen 2 für Syntaxfehler in der Kommandozeile und 1 für alle anderen Fehler, und 0 steht für Erfolg. argparse beendet sich bei ungültigen Argumenten bereits mit Status 2. Weitere Codes aus sysexits.h (EX_USAGE 64, EX_NOINPUT 66, EX_UNAVAILABLE 69, EX_TEMPFAIL 75) nur übernehmen, wenn --help sie dokumentiert.
4. Ergebnisse auf stdout schreiben und Diagnosemeldungen auf stderr. --json anbieten, wenn andere Programme die Ausgabe konsumieren, sowie --verbose/--quiet, die den Logging-Level setzen, statt print über den Code zu verstreuen.
5. Erwartete Fehler (FileNotFoundError, Verbindungsfehler, fachliche Ausnahmen) in main abfangen, eine Zeile auf stderr ausgeben und den dokumentierten Code zurückgeben; unerwartete Ausnahmen weiterreichen lassen, damit Traceback und Exit-Code 1 erhalten bleiben.
6. KeyboardInterrupt behandeln, indem aufgeräumt und 130 zurückgegeben wird, passend zur Shell-Konvention von 128 plus Signalnummer, und BrokenPipeError auf stdout abfangen, damit tool | head still endet.
7. Die Hilfe ehrlich halten: metavar für lesbare Platzhalter, ArgumentDefaultsHelpFormatter, damit Standardwerte erscheinen, und einen Test, der prüft, dass --help mit 0 endet.

Erwartetes Ergebnis

tool --help dokumentiert die gesamte Schnittstelle; tool --bad; echo $? gibt 2 aus; ein Eingabeproblem gibt eine Zeile auf stderr und einen dokumentierten Code aus; ein aufrufender Prozess kann anhand des Codes verzweigen, ohne Text zu parsen.

Grenzen und Prüfbasis

Die Dokumentation zu sys.exit merkt an, dass die meisten Systeme Exit-Codes im Bereich 0 bis 127 verlangen; Werte darüber kollidieren mit der Signalkodierung der Shell. exit_on_error=False lässt den Parser ArgumentError auslösen statt sich zu beenden, was sich für die Einbettung eignet, aber eine eigene Fehlerbehandlung braucht. Die Konventionen folgen der zitierten Dokumentation; es wird keine Messung der Benutzbarkeit behauptet.

Beenden nach Ctrl-C

Eine Shell entscheidet, ob eine Unterbrechung auch das umschliessende Skript stoppen soll, indem sie prüft, ob der Kindprozess durch SIGINT beendet wurde, nicht indem sie den Exit-Code liest. Ein Werkzeug, das KeyboardInterrupt abfängt und 130 zurückgibt, sieht deshalb wie ein normales Beenden aus, und for f in *; do tool "$f"; done fährt nach jedem Ctrl-C mit der nächsten Datei fort. Erst aufräumen, dann den Prozess so beenden, wie es eine unbehandelte Unterbrechung täte (Python macht das seit 3.8 von sich aus):

except KeyboardInterrupt:
    cleanup()
    signal.signal(signal.SIGINT, signal.SIG_DFL)
    os.kill(os.getpid(), signal.SIGINT)

$? liest weiterhin 130, und ein übergeordneter Prozess, der auf den Prozess wartet, sieht ein Sterben durch Signal. return 130 nur für aufrufende Stellen reservieren, von denen bekannt ist, dass sie ausschliesslich Codes lesen.