init at work

2026-03-27 12:58:01 +01:00
parent 352c352056
commit 8d40597732
60 changed files with 16498 additions and 0 deletions
@@ -0,0 +1,368 @@
+## 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()
+```
+
+---