pz-cli 5.0.0__py3-none-any.whl

pz_core/assembly/events/compiler.py

@@ -0,0 +1,219 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from pz_core.assembly.settings import SettingsSnapshot
+from pz_core.core.events import EventDecl, EventHandlerDecl, EventRegistry
+from pz_core.core.errors import PzError
+from pz_core.core.extensions import ExtensionRegistry
+
+
+@dataclass(frozen=True, slots=True)
+class EventDeclarationSource:
+    event: EventDecl
+    source: str
+
+
+def _read_required_string(
+    value: object,
+    *,
+    code: str,
+    message: str,
+    owner: str,
+) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise PzError(
+            code=code,
+            message=message,
+            stage="events",
+            owner=owner,
+            action="compile_event_registry",
+        )
+    return value.strip()
+
+
+def _read_optional_string(
+    value: object,
+    *,
+    code: str,
+    message: str,
+    owner: str,
+) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str) or not value.strip():
+        raise PzError(
+            code=code,
+            message=message,
+            stage="events",
+            owner=owner,
+            action="compile_event_registry",
+        )
+    return value.strip()
+
+
+def _read_declared_events(settings: SettingsSnapshot) -> tuple[EventDecl, ...]:
+    raw = settings.get("events", "declared", default={})
+    if raw in (None, {}):
+        return ()
+    if not isinstance(raw, dict):
+        raise PzError(
+            code="PZ_EVENT_DECLARED_INVALID",
+            message="events.declared must be a table keyed by event name.",
+            stage="events",
+            owner="events",
+            action="compile_event_registry",
+        )
+
+    events: list[EventDecl] = []
+    for event_name, payload in raw.items():
+        name = _read_required_string(
+            event_name,
+            code="PZ_EVENT_NAME_INVALID",
+            message="events.declared contains an event name that is not a non-empty string.",
+            owner="events",
+        )
+        if not isinstance(payload, dict):
+            raise PzError(
+                code="PZ_EVENT_DECL_INVALID",
+                message=f"Event '{name}' must be declared as a table.",
+                stage="events",
+                owner=name,
+                action="compile_event_registry",
+            )
+        owner = _read_required_string(
+            payload.get("owner"),
+            code="PZ_EVENT_OWNER_INVALID",
+            message=f"Event '{name}' must declare owner as a non-empty string.",
+            owner=name,
+        )
+        payload_schema = _read_optional_string(
+            payload.get("payload_schema"),
+            code="PZ_EVENT_PAYLOAD_SCHEMA_INVALID",
+            message=f"Event '{name}' payload_schema must be a non-empty string when declared.",
+            owner=name,
+        )
+        events.append(EventDecl(name=name, owner=owner, payload_schema=payload_schema))
+    return tuple(events)
+
+
+def _read_extension_declared_events(
+    extension_registry: ExtensionRegistry | None,
+) -> tuple[EventDecl, ...]:
+    if extension_registry is None:
+        return ()
+
+    events: list[EventDecl] = []
+    for extension in extension_registry.by_kind("event.declaration"):
+        owner = _read_required_string(
+            getattr(extension, "owner_app", None),
+            code="PZ_EVENT_EXTENSION_OWNER_INVALID",
+            message="event.declaration must declare owner_app as a non-empty string.",
+            owner="events",
+        )
+        payload = getattr(extension, "payload", None)
+        if not isinstance(payload, dict):
+            raise PzError(
+                code="PZ_EVENT_EXTENSION_DECL_INVALID",
+                message=f"App '{owner}' event.declaration payload must be a table.",
+                stage="events",
+                owner=owner,
+                action="compile_event_registry",
+            )
+        name = _read_required_string(
+            payload.get("name"),
+            code="PZ_EVENT_EXTENSION_NAME_INVALID",
+            message=f"App '{owner}' event.declaration must declare payload.name as a non-empty string.",
+            owner=owner,
+        )
+        payload_schema = _read_optional_string(
+            payload.get("payload_schema"),
+            code="PZ_EVENT_EXTENSION_PAYLOAD_SCHEMA_INVALID",
+            message=(
+                f"App '{owner}' event.declaration payload_schema must be a non-empty string when declared."
+            ),
+            owner=name,
+        )
+        events.append(EventDecl(name=name, owner=owner, payload_schema=payload_schema))
+    return tuple(events)
+
+
+def _read_event_handlers(settings: SettingsSnapshot) -> tuple[EventHandlerDecl, ...]:
+    raw = settings.get("events", "handlers", default=())
+    if raw in (None, (), []):
+        return ()
+    if not isinstance(raw, list):
+        raise PzError(
+            code="PZ_EVENT_HANDLERS_INVALID",
+            message="events.handlers must be an array of tables.",
+            stage="events",
+            owner="events",
+            action="compile_event_registry",
+        )
+
+    handlers: list[EventHandlerDecl] = []
+    for index, payload in enumerate(raw):
+        if not isinstance(payload, dict):
+            raise PzError(
+                code="PZ_EVENT_HANDLER_DECL_INVALID",
+                message=f"events.handlers[{index}] must be a table.",
+                stage="events",
+                owner="events",
+                action="compile_event_registry",
+            )
+        event_name = _read_required_string(
+            payload.get("event"),
+            code="PZ_EVENT_HANDLER_EVENT_INVALID",
+            message=f"events.handlers[{index}] must declare event as a non-empty string.",
+            owner="events",
+        )
+        import_path = _read_required_string(
+            payload.get("import_path"),
+            code="PZ_EVENT_HANDLER_IMPORT_INVALID",
+            message=(
+                f"events.handlers[{index}] for event '{event_name}' must declare "
+                "import_path as a non-empty string."
+            ),
+            owner=event_name,
+        )
+        owner = _read_required_string(
+            payload.get("owner"),
+            code="PZ_EVENT_HANDLER_OWNER_INVALID",
+            message=(
+                f"events.handlers[{index}] for event '{event_name}' must declare "
+                "owner as a non-empty string."
+            ),
+            owner=event_name,
+        )
+        handlers.append(
+            EventHandlerDecl(
+                event=event_name,
+                import_path=import_path,
+                owner=owner,
+            )
+        )
+    return tuple(handlers)
+
+
+def collect_event_declarations(
+    settings: SettingsSnapshot,
+    extension_registry: ExtensionRegistry | None = None,
+) -> tuple[EventDeclarationSource, ...]:
+    declarations: list[EventDeclarationSource] = []
+    for event in _read_declared_events(settings):
+        declarations.append(EventDeclarationSource(event=event, source="project.settings"))
+    for event in _read_extension_declared_events(extension_registry):
+        declarations.append(EventDeclarationSource(event=event, source="app.extension"))
+    return tuple(declarations)
+
+
+def compile_event_registry(
+    settings: SettingsSnapshot,
+    extension_registry: ExtensionRegistry | None = None,
+) -> EventRegistry:
+    registry = EventRegistry(
+        events=tuple(item.event for item in collect_event_declarations(settings, extension_registry)),
+        handlers=_read_event_handlers(settings),
+    )
+    registry.validate()
+    return registry

pz_core/assembly/extensions/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from .compiler import compile_extension_registry
+
+__all__ = ["compile_extension_registry"]