Zum Inhalt

Usage

Grundlegende Verwendung

Das Form Download Helper Tool wird über die Kommandozeile verwendet:

form-download-helper <path> <username> <password> <version> <uri> [--package <package>]

Parameter

Parameter Beschreibung Beispiel
path Zielverzeichnis für Downloads /tmp/ozg
username Benutzername für HTTP Basic Auth ck@novareto.de
password Passwort für HTTP Basic Auth mein-passwort
version Versionsnummer des Formulars 2
uri URI des Formulars https://formulare.uv-kooperation.de/ozg/rul/ozg-90
package (Optional) Python-Paketname myapp.forms

Der package-Parameter wird automatisch aus dem Zielpfad und der Projektstruktur abgeleitet, wenn er nicht angegeben wird.

Beispiele

Basis-Download

form-download-helper /tmp/ozg ck@novareto.de mein-passwort 2 https://formulare.uv-kooperation.de/ozg/rul/ozg-90

Mit verschiedenen Versionen

# Version 1 herunterladen
form-download-helper /tmp/ozg ck@novareto.de mein-passwort 1 https://formulare.uv-kooperation.de/ozg/rul/ozg-90

# Version 3 herunterladen
form-download-helper /tmp/ozg ck@novareto.de mein-passwort 3 https://formulare.uv-kooperation.de/ozg/rul/ozg-90

Mit explizitem Paketnamen

form-download-helper /tmp/ozg ck@novareto.de mein-passwort 2 https://formulare.uv-kooperation.de/ozg/rul/ozg-90 --package myapp.forms

Ausgabestruktur

Nach dem Download wird folgende Verzeichnisstruktur erstellt:

Standard-Formular

<zielverzeichnis>/
└── <formular-name>/
    ├── __init__.py
    ├── form.py              # Generierte Python Formularklasse
    └── v<version>/
        ├── __init__.py
        ├── schema.json       # JSON Schema des Formulars
        ├── ui_schema.json    # UI Schema des Formulars
        ├── template.pt       # Page Template
        └── tests/
            ├── __init__.py
            ├── test_<formname>.py    # Generierte Tests
            └── test_acceptance.py    # Akzeptanz-Tests

Wizard-Formular

Wizard-Formulare erzeugen zusätzlich ein steps/-Verzeichnis:

<zielverzeichnis>/
└── <formular-name>/
    ├── __init__.py
    ├── form.py
    └── v<version>/
        ├── __init__.py
        ├── schema.json
        ├── ui_schema.json
        ├── template.pt
        ├── wizard_template.pt    # Wizard-Mode Template
        ├── steps/
        │   └── <step-name>/
        │       ├── __init__.py
        │       ├── schema.json
        │       ├── ui_schema.json
        │       └── template.pt
        └── tests/
            ├── __init__.py
            ├── test_<formname>.py
            └── test_acceptance.py

Generierte Dateien

schema.json

Enthält das JSON Schema des Formulars mit allen Felddefinitionen (von @@meta-schema).

ui_schema.json

UI Schema mit Layout- und Darstellungsinformationen (von @@simple-ui-schema-view).

template.pt

Page Template für die Formular-Darstellung (von @@cpt-generator). Bei Wizard-Formularen wird stattdessen ein vorgefertigtes Wizard-Template verwendet.

wizard_template.pt

Zusätzliches Template für den Wizard-Modus (nur bei Wizard-Formularen).

form.py

Generierte Python-Klasse mit:

  • OZG Form Klasse für OZG-Anwendungen
  • REHA Form Klasse für REHA-Anwendungen
  • Mixin mit gemeinsamer Funktionalität

Hinweis

form.py wird nur erstellt, wenn die Datei noch nicht existiert. Bestehende Dateien werden übersprungen, um manuelle Anpassungen zu erhalten.

test_.py

Grundlegende Tests für die generierten Formularklassen.

test_acceptance.py

Akzeptanz-Tests für das Formular.

Versionierung

Das Tool verwendet ein spezifisches Versionierungsformat:

  • Input: 2 → Output: v2_0
  • Input: 2.5 → Output: v2_5

Formularnamen

Der Formularname wird aus dem JSON-Schema (name-Feld) abgeleitet. Falls der Server unknown_form zurückgibt, wird der Name automatisch aus dem URI-Slug generiert:

  • https://example.de/ozg/rul/anfrage-zahnarzt → anfrage_zahnarzt

Namen, die mit einer Ziffer beginnen, erhalten das Präfix F_:

  • 90_form → F_90_form

Authentifizierung

Das Tool verwendet HTTP Basic Authentication:

# Benutzername und Passwort werden direkt übertragen
# Stellen Sie sicher, dass HTTPS verwendet wird

Sicherheitshinweis

Verwenden Sie keine Passwörter direkt in Skripten oder Logs. Nutzen Sie Umgebungsvariablen für sensible Daten.

Generierte Tests (pytest)

Das Tool generiert automatisch zwei Testdateien pro Formular im Verzeichnis tests/:

test_.py

Ein Basis-Test, der prüft ob das Formular korrekt im document_stores registriert ist:

def test_base(loaded_app):
    assert "<form_name>" in loaded_app.document_stores["ozg"].keys()

test_acceptance.py

Akzeptanz-Tests mit pytest.mark.acceptance, die das Formular im Browser rendern und prüfen:

import pytest

FORM_NAME = "<form_name>"

@pytest.mark.acceptance
def test_form_renders(page, live_server, form_url):
    url = f"{live_server}{form_url(FORM_NAME)}"
    response = page.goto(url)
    assert response.status == 200
    assert page.locator("form").count() > 0

Test-Verzeichnisstruktur

Jedes Versions-Verzeichnis enthält ein eigenes tests/-Paket:

v2_0/
└── tests/
    ├── __init__.py            # Macht tests/ zu einem Python-Paket
    ├── test_<formname>.py     # Basis-Tests
    └── test_acceptance.py     # Akzeptanz-Tests (Browser)

Hinweis

Die __init__.py in tests/ verhindert pytest-Import-Konflikte beim Sammeln von Tests aus mehreren Formular-Verzeichnissen. Die Testdatei wird nach dem Formularnamen benannt (test_<formname>.py), um Namenskollisionen zu vermeiden.

Widget Overrides und UI-Schema

Die generierten Formularklassen nutzen OverrideTemplateLoader und WIDGETS für eine flexible Anpassung der Darstellung.

OverrideTemplateLoader

from uv.formulare.helpers import OverrideTemplateLoader

TEMPLATES = OverrideTemplateLoader(".")

OverrideTemplateLoader(".") sucht Templates relativ zum aktuellen Paket. Die template-Property in FormMixin lädt das versionierte Template:

@property
def template(self):
    return TEMPLATES[f"{self.version}/template.pt"]

UI-Schema und Widget-Mapping

Standard-Formulare laden das UI-Schema und wenden es auf das Colander-Schema an:

from jsonschema_ui import apply_ui_to_colander
from uv.formulare.helpers import load_ui_schema
from ritter_deform.jsonschema import WIDGETS

def get_schema(self):
    base_schema = super().get_schema()
    schema = apply_ui_to_colander(
        base_schema, load_ui_schema(__file__, self.version), WIDGETS
    )
    return schema
  • load_ui_schema(__file__, self.version) – lädt ui_schema.json aus dem Versions-Verzeichnis
  • WIDGETS – Standard-Widget-Mappings aus ritter_deform.jsonschema
  • apply_ui_to_colander – wendet UI-Schema-Overrides auf das Colander-Formularschema an

Wizard Widget-Konfiguration

Wizard-Formulare verwenden DEFAULT_WIDGETS aus uv.formulare.widgets:

from uv.formulare.widgets import DEFAULT_WIDGETS as widgets

class FormMixin(SectionFormMixin):   # oder WizardFormMixin
    wizard_widgets = widgets

Rendering-Modi bei Wizards

Wizard-Formulare unterstützen zwei Darstellungsmodi, steuerbar über USE_WIZARD in form.py:

Modus USE_WIZARD Template Beschreibung
Section-Modus False template.pt Alle Steps auf einer Seite als Fieldsets
Wizard-Modus True wizard_template.pt Multi-Step mit Zurück/Weiter-Navigation

Fehlerbehebung

Authentifizierungsfehler

# Überprüfen Sie Benutzername und Passwort
# Stellen Sie sicher, dass der Account Zugriff hat

Netzwerkfehler

# Überprüfen Sie die URI
# Testen Sie die Verbindung mit curl:
curl -u username:password "https://formulare.uv-kooperation.de/ozg/rul/ozg-90/@@meta-schema?version=2"

Dateisystem-Fehler

# Stellen Sie sicher, dass das Zielverzeichnis beschreibbar ist
# Überprüfen Sie verfügbaren Speicherplatz