it-know-how/python/argpase.md

1. Grundidee von argparse

argparse ist das Standardmodul in Python, um Kommandozeilen-Argumente zu definieren, zu parsen und automatisch Hilfe-/Usage-Texte zu erzeugen.

Minimalbeispiel:

import argparse

parser = argparse.ArgumentParser(description="Ein kleines Beispiel-CLI")
parser.add_argument("datei", help="Pfad zur Eingabedatei")
args = parser.parse_args()

print(args.datei)

Aufruf:

python script.py meine_datei.txt

---

2. Argumente definieren: ArgumentParser.add_argument

2.1 Positionsargumente

• Werden ohne führende - oder -- angegeben.
• Reihenfolge ist relevant.

parser.add_argument("quelle", help="Quellpfad")
parser.add_argument("ziel", help="Zielpfad")

Aufruf:

python script.py input.txt output.txt

Use-Case:

• Pflichtwerte, die immer gebraucht werden (z.B. Eingabe- und Ausgabedatei).

---

2.2 Optionale Argumente (Flags / Optionen)

• Beginnen mit - bzw. --.
• Reihenfolge ist egal.
• Können Standardwerte haben.

parser.add_argument(
    "-v", "--verbose",
    action="store_true",
    help="Ausführliche Ausgabe aktivieren"
)

parser.add_argument(
    "-n", "--anzahl",
    type=int,
    default=10,
    help="Anzahl der Elemente (Standard: 10)"
)

Aufruf:

python script.py input.txt --verbose --anzahl 5
# oder kurz:
python script.py input.txt -v -n 5

Use-Case:

• Konfiguration, optionales Verhalten, Debug/Verbose-Flags, Parameter mit Default.

---

3. Wichtige Parameter von add_argument

3.1 name / flags

• Beispiel:
  • Positional: "datei"
  • Optional: "-v", "--verbose"

parser.add_argument("datei")
parser.add_argument("-v", "--verbose")

---

3.2 type

• Convertiert Eingabe in Typ.
• Validiert automatisch (bei falschem Typ Fehler + Hilfe).

parser.add_argument("--port", type=int, default=8080)
parser.add_argument("--faktor", type=float)

Use-Case:

• Numerische Werte, Pfade, eigene Typen (z.B. Path aus pathlib).

---

3.3 default

• Standardwert, wenn Argument nicht übergeben wird.

parser.add_argument("--log-level", default="INFO")

Use-Case:

• Sinnvolle Defaults, um CLI kompakt zu halten.

---

3.4 required

• Macht optionale Argumente zwingend erforderlich.

parser.add_argument("--config", required=True)

Use-Case:

• Flags/Optionen, die zwingend gesetzt werden müssen (z.B. API-Key, Konfigdatei).

---

3.5 help

• Beschreibung für die --help-Ausgabe.

parser.add_argument("--mode", help="Betriebsmodus: fast oder safe")

Use-Case:

• Dokumentation der Optionen (sehr wichtig für Benutzerfreundlichkeit).

---

3.6 choices

• Schränkt erlaubte Werte ein.

parser.add_argument(
    "--mode",
    choices=["fast", "safe"],
    default="safe",
    help="fast = schneller, safe = sicherer"
)

Use-Case:

• Enum-ähnliche Optionen (z.B. debug/info/warn/error, json/text).

---

3.7 action

Steuert, was passiert, wenn das Argument gesetzt wird.

Häufige Actions:

1. store (Standard)
   Speichert den Wert (z.B. --port 8000 → args.port = 8000).

2. store_true / store_false
   Boolean-Flag, das True/False setzt.

   parser.add_argument("-v", "--verbose", action="store_true")
   

3. append
   Fügt mehrere Werte in eine Liste ein.

   parser.add_argument(
       "-t", "--tag",
       action="append",
       help="Kann mehrfach verwendet werden"
   )
   # Aufruf: --tag a --tag b -> args.tag = ["a", "b"]
   

4. count
   Zählt, wie oft ein Flag verwendet wurde.

   parser.add_argument(
       "-v", "--verbose",
       action="count",
       default=0,
       help="Mehrfach verwenden für mehr Details"
   )
   # -v -> 1, -vv -> 2 ...
   

Use-Case:

• Flags (bool), Mehrfachangaben (Listen), Verbosity-Level etc.

---

3.8 nargs

Gibt an, wie viele Werte zu einem Argument gehören.

Typische Varianten:

• nargs=1 → eine Liste mit einem Element
• nargs=2 → genau 2 Werte
• nargs="+" → mindestens ein Wert
• nargs="*" → beliebig viele (auch 0)

parser.add_argument("dateien", nargs="+", help="Eine oder mehrere Dateien")
parser.add_argument("--koordinaten", nargs=2, type=float, help="x y")

Use-Case:

• Mehrere Dateien, Koordinaten, Listen von Werten.

---

3.9 metavar

• Steuert, wie das Argument im Help-Text angezeigt wird.

parser.add_argument(
    "--output",
    metavar="DATEI",
    help="Ausgabedatei"
)

Use-Case:

• Schöner formatierte Hilfe (statt generischer Namen).

---

3.10 dest

• Name des Attributes in args.

parser.add_argument("-o", "--output", dest="ausgabedatei")
# args.ausgabedatei

Use-Case:

• Lesbare/konfliktfreie Python-Bezeichner, wenn CLI-Namen nicht ideal sind.

---

4. Subkommandos: subparsers

Für CLI-Tools mit mehreren Befehlen (ähnlich git commit, git status).

import argparse

parser = argparse.ArgumentParser(prog="tool")
subparsers = parser.add_subparsers(dest="command", required=True)

# Subkommando: "run"
run_parser = subparsers.add_parser("run", help="Job ausführen")
run_parser.add_argument("job_id", type=int)

# Subkommando: "list"
list_parser = subparsers.add_parser("list", help="Jobs auflisten")
list_parser.add_argument("--status", choices=["open", "done"])

args = parser.parse_args()

if args.command == "run":
    print(f"Starte Job {args.job_id}")
elif args.command == "list":
    print(f"Liste Jobs mit Status {args.status}")

Aufrufe:

tool run 42
tool list --status open

Use-Case:

• Umfangreiche Tools mit verschiedenen Befehlen (z.B. Admin-Tools, Deployment-CLI).

---

5. Automatische Hilfe und Usage

argparse erzeugt automatisch -h / --help:

python script.py --help

Du bekommst:

• Beschreibung (description)
• Liste aller Argumente
• Default-Werte (wenn konfiguriert)
• Subkommandos (falls vorhanden)

Beispiel:

parser = argparse.ArgumentParser(
    description="Konvertiert Dateien in andere Formate."
)

---

6. Minimaler „Best-Practice“-Skeleton

import argparse

def parse_args():
    parser = argparse.ArgumentParser(
        description="Beispiel-Tool für argparse"
    )

    # Positionsargumente
    parser.add_argument("eingabe", help="Eingabedatei")

    # Optionale Argumente
    parser.add_argument(
        "-o", "--output",
        help="Ausgabedatei (Standard: stdout)"
    )
    parser.add_argument(
        "-v", "--verbose",
        action="store_true",
        help="Ausführliche Ausgabe"
    )
    parser.add_argument(
        "--mode",
        choices=["fast", "safe"],
        default="safe",
        help="Verarbeitungsmodus (Standard: safe)"
    )

    return parser.parse_args()

def main():
    args = parse_args()
    if args.verbose:
        print(f"Starte in Modus {args.mode} mit Eingabe {args.eingabe}")
    # weitere Logik…

if __name__ == "__main__":
    main()

---