Zum Inhalt

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:

uv tool install form-download-helper

3. Aktualisieren:

uv tool upgrade form-download-helper

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

pip install git+https://git.bg-kooperation.de/novareto/form_download_helper.git

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 Framework
  • requests>=2.31.0 - HTTP Client
  • rich - 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.

make help          # Übersicht aller Targets

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:

make hooks
# manuell mit uv:
uv run --extra dev pre-commit install

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:

python --version

Netzwerk-Probleme

Bei Problemen mit dem Git-Repository:

# SSH statt HTTPS verwenden
pip install git+ssh://git@git.bg-kooperation.de/novareto/form_download_helper.git