Emzett Digital

Kommandozeilen-Programme mit argparse

Viele nützliche Programme laufen im Terminal und bekommen ihre Eingaben über Argumente: python rechne.py 3 4 --operation mult. Das Modul argparse baut dafür eine saubere Befehlszeile mit Hilfetext und Fehlermeldungen.

sys.argv: das Rohe

Alle Argumente landen als Liste von Texten in sys.argv. Das erste Element ist der Programmname:

python

import sys

# Simuliert: python programm.py hallo welt
sys.argv = ["programm.py", "hallo", "welt"]
print(sys.argv[0])
print(sys.argv[1:])

Ausgabe

programm.py
['hallo', 'welt']

Für alles über ein oder zwei Argumente hinaus lohnt sich argparse.

Ein erstes Programm

python

import argparse

parser = argparse.ArgumentParser(description="Begrüßt jemanden")
parser.add_argument("name", help="Name der Person")
parser.add_argument("--laut", action="store_true", help="in Großbuchstaben")
parser.add_argument("-n", "--anzahl", type=int, default=1, help="wie oft")

args = parser.parse_args(["Mia", "--laut", "-n", "2"])   # normalerweise: parse_args()
text = f"Hallo {args.name}!"
if args.laut:
    text = text.upper()
for _ in range(args.anzahl):
    print(text)

Ausgabe

HALLO MIA!
HALLO MIA!

Positionsargumente (name) sind Pflicht und stehen an fester Stelle.
Optionen beginnen mit - oder -- und sind meist optional.
action="store_true" macht aus der Option einen Schalter ohne Wert.
type=int wandelt den Text um und meldet Fehler bei ungültigen Eingaben.

Im echten Programm rufst du einfach parser.parse_args() ohne Liste auf; dann liest argparse sys.argv.

Automatische Hilfe

python

import argparse

p = argparse.ArgumentParser(prog="rechne", description="Kleiner Taschenrechner")
p.add_argument("a", type=float)
p.add_argument("b", type=float)
p.add_argument("--op", choices=["plus", "mal"], default="plus", help="Rechenart")
print(p.format_help())

Ausgabe

usage: rechne [-h] [--op {plus,mal}] a b

Kleiner Taschenrechner

positional arguments:
  a
  b

options:
  -h, --help       show this help message and exit
  --op {plus,mal}  Rechenart

Mit -h oder --help zeigt jedes argparse-Programm diesen Text automatisch.

Fehlerbehandlung

Bei ungültigen Eingaben beendet argparse das Programm mit einer verständlichen Fehlermeldung und Exit-Code 2:

python

import argparse

p = argparse.ArgumentParser(prog="rechne")
p.add_argument("zahl", type=int)

try:
    p.parse_args(["abc"])
except SystemExit as e:
    print("Beendet mit Code", e.code)

Ausgabe

Beendet mit Code 2

Unterbefehle

Programme wie git commit und git push nutzen Unterbefehle:

python

import argparse

p = argparse.ArgumentParser(prog="todo")
sub = p.add_subparsers(dest="befehl", required=True)

neu = sub.add_parser("neu", help="Eintrag anlegen")
neu.add_argument("text")

sub.add_parser("liste", help="alle Einträge zeigen")

print(p.parse_args(["neu", "Milch kaufen"]))
print(p.parse_args(["liste"]))

Ausgabe

Namespace(befehl='neu', text='Milch kaufen')
Namespace(befehl='liste')

Typischer Aufbau

text

import argparse

def main():
    parser = argparse.ArgumentParser(description="...")
    parser.add_argument("datei")
    args = parser.parse_args()
    # ... Arbeit mit args.datei ...

if __name__ == "__main__":
    main()

Die Zeile if __name__ == "__main__": startet main() nur, wenn die Datei direkt ausgeführt wird, nicht beim Import als Modul.

Merke

sys.argv enthält die Rohargumente
argparse.ArgumentParser baut Positionsargumente, Optionen und Schalter
type=, default=, choices= und help= steuern Prüfung und Hilfe
-h erzeugt automatisch eine Hilfe
Unterbefehle mit add_subparsers
if __name__ == "__main__": main() als Einstiegspunkt

Aufgabe

Schreibe ein Programm zaehle.py, das mit --zeilen die Zeilen einer Datei zählt und mit --woerter die Wörter.

sys.argv: das Rohe

Alle Argumente landen als Liste von Texten in sys.argv. Das erste Element ist der Programmname:

python

import sys

# Simuliert: python programm.py hallo welt
sys.argv = ["programm.py", "hallo", "welt"]
print(sys.argv[0])
print(sys.argv[1:])

Ausgabe

programm.py
['hallo', 'welt']

Für alles über ein oder zwei Argumente hinaus lohnt sich argparse.

Ein erstes Programm

python

import argparse

parser = argparse.ArgumentParser(description="Begrüßt jemanden")
parser.add_argument("name", help="Name der Person")
parser.add_argument("--laut", action="store_true", help="in Großbuchstaben")
parser.add_argument("-n", "--anzahl", type=int, default=1, help="wie oft")

args = parser.parse_args(["Mia", "--laut", "-n", "2"])   # normalerweise: parse_args()
text = f"Hallo {args.name}!"
if args.laut:
    text = text.upper()
for _ in range(args.anzahl):
    print(text)

Ausgabe

HALLO MIA!
HALLO MIA!

Positionsargumente (name) sind Pflicht und stehen an fester Stelle.
Optionen beginnen mit - oder -- und sind meist optional.
action="store_true" macht aus der Option einen Schalter ohne Wert.
type=int wandelt den Text um und meldet Fehler bei ungültigen Eingaben.

Im echten Programm rufst du einfach parser.parse_args() ohne Liste auf; dann liest argparse sys.argv.

Automatische Hilfe

python

import argparse

p = argparse.ArgumentParser(prog="rechne", description="Kleiner Taschenrechner")
p.add_argument("a", type=float)
p.add_argument("b", type=float)
p.add_argument("--op", choices=["plus", "mal"], default="plus", help="Rechenart")
print(p.format_help())

Ausgabe

usage: rechne [-h] [--op {plus,mal}] a b

Kleiner Taschenrechner

positional arguments:
  a
  b

options:
  -h, --help       show this help message and exit
  --op {plus,mal}  Rechenart

Mit -h oder --help zeigt jedes argparse-Programm diesen Text automatisch.

Fehlerbehandlung

Bei ungültigen Eingaben beendet argparse das Programm mit einer verständlichen Fehlermeldung und Exit-Code 2:

python

import argparse

p = argparse.ArgumentParser(prog="rechne")
p.add_argument("zahl", type=int)

try:
    p.parse_args(["abc"])
except SystemExit as e:
    print("Beendet mit Code", e.code)

Ausgabe

Beendet mit Code 2

Unterbefehle

Programme wie git commit und git push nutzen Unterbefehle:

python

import argparse

p = argparse.ArgumentParser(prog="todo")
sub = p.add_subparsers(dest="befehl", required=True)

neu = sub.add_parser("neu", help="Eintrag anlegen")
neu.add_argument("text")

sub.add_parser("liste", help="alle Einträge zeigen")

print(p.parse_args(["neu", "Milch kaufen"]))
print(p.parse_args(["liste"]))

Ausgabe

Namespace(befehl='neu', text='Milch kaufen')
Namespace(befehl='liste')

Typischer Aufbau

text

import argparse

def main():
    parser = argparse.ArgumentParser(description="...")
    parser.add_argument("datei")
    args = parser.parse_args()
    # ... Arbeit mit args.datei ...

if __name__ == "__main__":
    main()

Die Zeile if __name__ == "__main__": startet main() nur, wenn die Datei direkt ausgeführt wird, nicht beim Import als Modul.

Merke

sys.argv enthält die Rohargumente
argparse.ArgumentParser baut Positionsargumente, Optionen und Schalter
type=, default=, choices= und help= steuern Prüfung und Hilfe
-h erzeugt automatisch eine Hilfe
Unterbefehle mit add_subparsers
if __name__ == "__main__": main() als Einstiegspunkt

Aufgabe

Schreibe ein Programm zaehle.py, das mit --zeilen die Zeilen einer Datei zählt und mit --woerter die Wörter.