merging and cleaning up

2026-03-27 13:14:52 +01:00
parent 4eb84a28af
commit 82d7e0e888
62 changed files with 6 additions and 386 deletions
@@ -1,385 +0,0 @@
 # 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()
 ```
 ---
@@ -1 +1,6 @@
-unison "$HOME/links/mathias_dfine_vault/Know-How/" "$HOME/it-know-how/" -perms 0
+unison \
    "$HOME/links/mathias_dfine_vault/Know-How/" \
    "$HOME/it-know-how/" \
    -perms 0 \
    -ignore 'Path .git' \
    -ignore 'Regex .*\.sh$'