Entwickler-Handbuch: Plugin Lifecycle Hooks

HOOK_PLUGIN_LOAD = ‘on_plugin_load’ HOOK_FILE_LOAD = ‘on_file_load’ HOOK_RELOAD = ‘on_reload’ HOOK_UPSTREAM = ‘on_folder_change’

Aura SL5 ermöglicht es Plugins (Maps), spezifische “Hooks” (Einhängepunkte) zu definieren, die automatisch ausgeführt werden, wenn sich der Status eines Moduls ändert. Dies ist essenziell für fortgeschrittene Workflows wie das Secure Private Map System.

Der on_reload() Hook

Die Funktion on_reload() ist eine optionale Funktion, die du in jedem Map-Modul definieren kannst.

Verhalten

  • Auslöser: Wird unmittelbar ausgeführt, nachdem ein Modul erfolgreich per Hot-Reload neu geladen wurde (Dateiänderung + Sprach-Trigger).

  • Kontext: Läuft innerhalb des Haupt-Anwendungs-Threads (Main Thread).

  • Sicherheit: Ist in einen try/except-Block gekapselt. Fehler, die hier auftreten, werden protokolliert, führen aber nicht zum Absturz der Anwendung.

Verwendungsmuster: Die “Daisy Chain” (Delegation)

Bei komplexen Paketen (wie Private Maps) hast du oft viele Unterdateien, aber nur ein zentrales Skript (z. B. secure_packer.py), das die Logik (wie das Zippen) steuern soll.

Du kannst den Hook nutzen, um die Aufgabe “nach oben” zu delegieren:

# Example: Delegating logic to a parent script
import importlib.util
from pathlib import Path
import logging

logger = logging.getLogger(__name__)

def on_reload():
    """
    Searches for 'secure_packer.py' in parent directories and executes it.
    """
    logger.info("🔄 Map modified. Triggering packer...")
    
    current_path = Path(__file__).resolve()
    search_dir = current_path.parent
    packer_script = None

    # Search upwards (max 4 levels)
    for _ in range(4):
        candidate = search_dir / "secure_packer.py"
        if candidate.exists():
            packer_script = candidate
            break
        if search_dir.name in ["maps", "config"]: break
        search_dir = search_dir.parent

    if packer_script:
        try:
            # Dynamic Import & Execution
            spec = importlib.util.spec_from_file_location("packer_dyn", packer_script)
            module = importlib.util.module_from_spec(spec)
            spec.loader.exec_module(module)
            
            if hasattr(module, 'on_reload'):
                module.on_reload()
        except Exception as e:
            logger.error(f"❌ Failed to run packer: {e}")

Best Practices (Bewährte Vorgehensweisen)

  1. Halte es schnell: Führe keine langwierigen, blockierenden Aufgaben (wie riesige Downloads) direkt im Hook aus. Nutze Threads, wenn nötig.

  2. Idempotenz: Stelle sicher, dass dein Hook mehrfach ausgeführt werden kann, ohne Schaden anzurichten (z. B. hänge Text nicht endlos an eine Datei an, sondern überschreibe sie oder prüfe vorher).