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

Ziel

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

Voraussetzungen

Ein Package 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 sys.argv[1:] als Rückfalloption) 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 Rückgabewert und 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 Aufruffehler 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 sys.exit-Dokumentation 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 von sich aus 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 verstreut einzusetzen.
5. Erwartete Fehlschläge (FileNotFoundError, Verbindungsfehler, fachliche Exceptions) in main abfangen, eine Zeile auf stderr ausgeben und den dokumentierten Code zurückgeben; unerwartete Exceptions durchreichen 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 ein Test, 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 sowie einen dokumentierten Code aus; ein Aufrufer kann anhand des Codes verzweigen, ohne Text parsen zu müssen.

Grenzen und Prüfbasis

Die sys.exit-Dokumentation weist darauf hin, 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 bringt den Parser dazu, ArgumentError auszulö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 gestorben ist, nicht indem sie den Exit-Code liest. Ein Werkzeug, das KeyboardInterrupt abfängt und 130 zurückgibt, sieht deshalb wie ein normales Ende 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 so):

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

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