Installation
Voraussetzungen
- Python >= 3.12
- Git-Zugriff auf das Repository
- Internetverbindung für das Herunterladen von Formularen
- uv (empfohlen) oder pip
Installation mit uv (empfohlen)
uv ist ein schneller Python Package Manager. Installation:
# uv installieren (falls noch nicht vorhanden)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Als CLI-Tool aus dem Git Repository installieren
uv tool install "form-download-helper @ git+https://git.bg-kooperation.de/novareto/form_download_helper.git"
Installation aus der GitLab Package Registry (PyPI)
Veröffentlichte Versionen liegen in der PyPI-Registry der Gruppe novareto (ID 32) — sie genügt als Index für alle novareto-Pakete.
1. Registry einrichten — einmalig als globaler uv-Index konfigurieren:
mkdir -p ~/.config/uv
cat >> ~/.config/uv/uv.toml <<'EOF'
[[index]]
url = "https://git.bg-kooperation.de/api/v4/groups/32/-/packages/pypi/simple"
default = true
EOF
2. Mit uv tool installieren:
3. Aktualisieren:
Nach der Installation steht form-download-helper global zur Verfügung.
Die Registry erfordert Authentifizierung. Eine .netrc-Datei
(~/.netrc) kann dafür verwendet, werden, um die Authentifizierung für die PyPI-Registry bereitzustellen.
Installation mit pip
Entwicklungsinstallation
Mit uv (empfohlen)
# Repository klonen
git clone https://git.bg-kooperation.de/novareto/form_download_helper.git
cd form_download_helper
# Entwicklungsumgebung installieren (Lint-/Test-/Docs-Tools)
make dev # = uv sync --extra dev (nutzt uv.lock, Python aus .python-version)
# Git-Hooks installieren (führt vor jedem Commit "make check" aus)
make hooks
Mit pip
# Repository klonen
git clone https://git.bg-kooperation.de/novareto/form_download_helper.git
cd form_download_helper
# Development-Modus mit dev-Abhängigkeiten
pip install -e ".[dev]"
Abhängigkeiten
Das Tool benötigt folgende Python-Pakete:
typer>=0.12.3- CLI Frameworkrequests>=2.31.0- HTTP Clientrich- Terminal-Formatierung (wird automatisch installiert)
Überprüfung der Installation
Nach der Installation können Sie überprüfen, ob alles korrekt funktioniert:
# Mit uv
uv run form-download-helper --help
# Oder falls global installiert
form-download-helper --help
Dies sollte die Hilfe-Ausgabe des Tools anzeigen.
Entwicklung
Alle Entwicklungs-Tasks laufen über das Makefile.
Installieren
make dev # Komplette Entwicklungsumgebung (Lint-/Test-/Docs-Tools)
# manuell mit uv:
uv sync --extra dev
# Nur Basis-Abhängigkeiten (reicht zum Bauen des Pakets):
make install
# manuell: uv sync
Code-Stil prüfen und korrigieren
make fix # ruff format + Auto-Fix (ändert Dateien)
# manuell: uv run ruff format && uv run ruff check --fix
make lint # ruff check (Linting, schreibgeschützt)
# manuell: uv run ruff check
make format-check # Format-Prüfung ohne Dateiänderungen
# manuell: uv run ruff format --check
make typecheck # Statisches Typ-Checking mit ty
# manuell: uv run ty check
Testen
make test # pytest mit Coverage
# manuell: uv run pytest --cov=form_download_helper --cov-report=xml --cov-report=term
make check # lint + format-check + typecheck + test (das, was die CI prüft)
Pre-commit-Hooks
Mit make hooks wird ein Git-Hook installiert, der vor jedem Commit
automatisch make check ausführt — fehlerhafter Code kann so gar nicht erst
committet werden:
Escape hatch für Ausnahmen: git commit --no-verify.
Bauen
make package # Wheel + sdist nach dist/ bauen
# manuell: uv build
make docs # Dokumentation nach site/ bauen (strict, wie in der CI)
# manuell: uv run mkdocs build --strict
make docs-serve # Dokumentation lokal mit Live-Reload anzeigen
# manuell: uv run mkdocs serve
Fehlerbehebung
Permission Denied Fehler
Falls Sie Berechtigungsfehler erhalten:
# Installation mit --user Flag
pip install --user git+https://git.bg-kooperation.de/novareto/form_download_helper.git
Python Version Konflikte
Sicherstellen, dass Sie Python 3.12 oder höher verwendet wird:
Netzwerk-Probleme
Bei Problemen mit dem Git-Repository: