# argpase

---

## 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:

```python
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:

```bash
python script.py meine_datei.txt
```

---

## 2. Argumente definieren: `ArgumentParser.add_argument`

### 2.1 Positionsargumente

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

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

Aufruf:

```bash
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.

```python
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:

```bash
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"`

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

---

### 3.2 `type`

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

```python
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.

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

Use-Case:

- Sinnvolle Defaults, um CLI kompakt zu halten.

---

### 3.4 `required`

- Macht optionale Argumente zwingend erforderlich.

```python
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.

```python
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.

```python
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.

   ```python
   parser.add_argument("-v", "--verbose", action="store_true")
   ```
3. `append`  
   Fügt mehrere Werte in eine Liste ein.

   ```python
   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.

   ```python
   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)

```python
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.

```python
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`.

```python
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`).

```python
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:

```bash
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`:

```bash
python script.py --help
```

Du bekommst:

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

Beispiel:

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

---

## 6. Minimaler „Best-Practice“-Skeleton

```python
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()
```

---