# Python-Projekt

## Python-Spezifika

- Python 3.10+ (native type hints: X | None, list[X])
- PEP 8 (Style), PEP 484 (Type Hints), PEP 257 (Docstrings)
- Type Hints: vollständig, keine typing.Any ohne Begründung

## Paketmanager & Tooling

- **uv** für Dependencies
- example_*.py Dateien bei Schnittstellenänderungen aktualisieren
- Wichtige uv Commands:
  - `uv sync` - Dependencies installieren
  - `uv sync --all-groups` - Mit allen Dev-Dependencies
  - `uv add <package>` - Package hinzufügen
  - `uv run <command>` - Command in venv ausführen

## Dokumentation

- Docstrings: Google-Style (Args/Returns/Raises/Examples)
- Code-Blöcke mit ` ```python`
- Deutsch erlaubt
- **MkDocs:** Nur aus Docstrings generieren, kein Extra-Content (außer Getting Started). Minimal!

## Error Handling

- Spezifische Exceptions (ValueError, TypeError, etc.)
- **Niemals** bare `except:` oder `except Exception:` ohne Begründung
- Bei externen Aufrufen: spezifische Fehler wrappen (z.B. `requests.RequestException → APIError`)

---

## Kritische Constraints

- NICHT modifizieren: automation.sdl - Schemas niemals brechen
- Client-API Breaking Changes erlaubt (PoC-Status)
- Bei API-Änderungen: example_*.py synchron halten

### Ruff Linting

- **WICHTIG**: VS Code Ruff-Plugin formatiert automatisch beim Speichern
- **Konflikt mit Edit-Tool**: Datei wird zwischen Read und Write modifiziert → "File has been unexpectedly modified"
- **Lösung**: Bei Ruff-Fehlern **immer `sed` über Bash verwenden** statt Edit-Tool

```bash
# ✅ Korrekt: sed für Ruff-Fixes
sed -i 's/OLD_PATTERN/NEW_PATTERN/g' path/to/file.py

# ❌ Vermeiden: Edit-Tool bei aktiven Linter-Plugins
# Führt zu Race Conditions mit Auto-Format
```

**Workflow bei `uv run ruff check` Fehlern:**

1. Ruff-Fehler analysieren
2. Mit `sed` alle Patterns in einem atomaren Schritt ersetzen
3. Mit `uv run ruff check .` verifizieren
