Scripting API

Die Scripting API bietet schreibgeschützten Zugriff auf DATAMIMIC-Kontextdaten aus benutzerdefinierten Python-Skripten. Verwende sie, um wiederverwendbare Funktionen zu erstellen, die aus script=-Ausdrücken aufgerufen werden können.

Note

Diese Seite dokumentiert die Python-Helfer-API, die während der Ausdrucksauswertung verfügbar ist. Wenn Du nach DSL-Regeln zur Variablenauflösung wie this.*, this.parent.* oder benannten verschachtelten Pfaden innerhalb von <generate> suchst, siehe Variablen-Scope in verschachtelten Generates. DateTimeGenerator(reference=...) unterstuetzt nur die Lookup-Teilmenge aus bare Identifiern, this.<field>, this.parent.<field> und root.<field>.

Übersicht

Feature	Beschreibung
Zweck	Zugriff auf Kontextdaten aus benutzerdefinierten Python-Funktionen
Zugriff	Schreibgeschützt (gibt Kopien zurück, keine Live-Referenzen)
Geltungsbereich	Funktioniert nur während der Ausdrucksauswertung

Schnellstart

1. Python-Skript erstellen

# my_functions.py
from datamimic_ee.scripting import load_memstore, get_variable

def get_customer_name(customer_id: str) -> str:
    """Kundenname aus Memstore nachschlagen."""
    customers = load_memstore("customers")
    for customer in customers:
        if customer.get("id") == customer_id:
            return customer.get("name", "Unbekannt")
    return "Nicht gefunden"

def format_amount(multiplier: float = 1.0) -> str:
    """Betrag des aktuellen Datensatzes mit Währung formatieren."""
    amount = get_variable("amount", 0)
    currency = get_variable("currency", "USD")
    return f"{currency} {amount * multiplier:,.2f}"

2. In XML-Modell verwenden

<setup>
    <!-- Dein Skript laden -->
    <execute uri="my_functions.py"/>

    <!-- Memstore mit Kundendaten füllen -->
    <memstore id="mem"/>
    <generate name="customers" source="data/customers.ent.csv" target="mem"/>

    <!-- Deine Funktionen in Ausdrücken verwenden -->
    <generate name="invoices" source="data/invoices.ent.csv" target="JSON">
        <!-- Quellspalten sind bereits im Kontext; <key> nur zum Überschreiben/Hinzufügen -->
        <key name="customer_name" script="get_customer_name(customer_id)"/>
        <key name="formatted_total" script="format_amount(1.1)"/>
    </generate>
</setup>

---

Datetime-Helfer In Ausdruecken

Datetime-Arithmetik steht auch direkt in script=...-Ausdruecken ohne Importe zur Verfuegung.

• add_days(dt, n)
• add_hours(dt, n)
• add_minutes(dt, n)
• add_seconds(dt, n)
• add_weeks(dt, n)
• add_months(dt, n)
• add_years(dt, n)
• date_offset(dt, '30d')
• start_of_day(dt), end_of_day(dt)
• start_of_month(dt), end_of_month(dt)
• start_of_year(dt), end_of_year(dt)

Datetime-Werte im Evaluator bieten ausserdem chainbare Methoden wie issue_at_raw.add_days(30) und created_at.add_months(1).end_of_month().

<generate name="invoice" count="1">
    <variable name="issue_at_raw" generator="DateTimeGenerator(value='2024-01-15 10:30:00')"/>
    <key name="due_date" script="issue_at_raw.add_days(30)" outDateFormat="%Y-%m-%d"/>
</generate>

Wichtig:

• Arithmetik ist bewusst raw-only.
• Nach outDateFormat sehen nachfolgende Ausdruecke einen String und kein Datetime mehr.
• Wenn ein formatierter Wert versehentlich verwendet wird, liefert die Runtime einen typisierten Script-Fehler mit Hinweis auf die Raw-Regel.
• Datencontainer behalten reale Underline-Keys wie _id und _dt waehrend der Ausdrucksauswertung bei. Diese gelten als Datenfelder und nicht als oeffentliche API fuer beliebige Objekt-Interna.

API-Referenz

Import

from datamimic_ee.scripting import (
    load_memstore,
    load_memstore_page,
    get_variable,
    get_property,
    get_current_product,
    get_record_position,
    get_context_info,
)

Funktionen

load_memstore(product_name) -> list[dict]

Alle Datensätze aus einem Memstore laden.

load_memstore_page(product_name, skip, limit) -> list[dict]

Eine Seite von Datensätzen aus dem Memstore laden (für große Datensätze).

get_variable(name, default=None) -> Any

Einen Variablenwert aus dem aktuellen Datensatzkontext abrufen.

get_property(name, default=None) -> Any

Eine Eigenschaft aus dem Root-Kontext abrufen (z.B. aus .properties-Dateien).

get_current_product() -> dict | None

Eine Kopie des aktuellen Produkts abrufen (alle bisher generierten Schlüssel).

get_record_position() -> int | None

Die 1-basierte Position des aktuellen Datensatzes abrufen.

get_context_info() -> dict

Einen schreibgeschützten Snapshot der Kontextmetadaten abrufen.

---

Wichtig: Nur während Auswertung

Nur innerhalb von Funktionen aufrufen

Die Scripting API funktioniert nur während der Ausdrucksauswertung. Rufe diese Funktionen nicht zur Modul-Importzeit auf.

Korrekt:

def my_function():
    # Wird während der Ausdrucksauswertung aufgerufen
    return load_memstore("data")  # Funktioniert

Falsch:

# Wird zur Importzeit aufgerufen - führt zu Fehler!
data = load_memstore("data")  # Fehler: I858

---

Best Practices

1. Funktionen definieren, nicht zur Importzeit ausführen - API funktioniert nur während der Auswertung
2. Standardwerte verwenden - Fehlende Variablen elegant behandeln
3. Teure Lookups cachen - Modulebene-Caches für wiederholte Lookups verwenden
4. Funktionen rein halten - Kontext nicht ändern; berechnete Werte zurückgeben
5. Funktionen dokumentieren - Anderen Teammitgliedern bei der Verwendung helfen