pz-cli 5.0.0__py3-none-any.whl

pz_core/core/errors/models.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(slots=True)
+class PzError(Exception):
+    code: str
+    message: str
+    stage: str
+    owner: str
+    action: str
+    summary: str | None = None
+    detail: str | None = None
+    context: dict[str, Any] | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        summary = self.summary or self.message
+        payload = {
+            "code": self.code,
+            "message": self.message,
+            "summary": summary,
+            "stage": self.stage,
+            "owner": self.owner,
+            "action": self.action,
+        }
+        if self.detail:
+            payload["detail"] = self.detail
+        if self.context:
+            payload.update(
+                {
+                    key: value
+                    for key, value in self.context.items()
+                    if key not in payload
+                }
+            )
+        return payload
+
+    def __str__(self) -> str:
+        summary = self.summary or self.message
+        if self.detail:
+            return f"[{self.code}] {summary}: {self.detail}"
+        return f"[{self.code}] {summary}"
+
+
+def _read_context_string(
+    value: object,
+    *,
+    field: str,
+    default: str,
+) -> str:
+    if value is None:
+        return default
+    if not isinstance(value, str) or not value.strip():
+        raise PzError(
+            code="PZ_ERROR_CONTEXT_INVALID",
+            message=f"error context field '{field}' must be a non-empty string.",
+            stage="errors",
+            owner="core.errors",
+            action="as_pz_error",
+        )
+    return value.strip()
+
+
+def _default_summary(*, stage: str, action: str) -> str:
+    normalized_stage = _read_context_string(stage, field="stage", default="runtime")
+    normalized_action = _read_context_string(action, field="action", default="unknown")
+    return (
+        f"Operation failed during {normalized_stage}::{normalized_action}."
+    )
+
+
+def as_pz_error(
+    exc: Exception,
+    *,
+    code: str = "PZ_RUNTIME_ERROR",
+    stage: str = "runtime",
+    owner: str = "runtime",
+    action: str = "unknown",
+) -> PzError:
+    if isinstance(exc, PzError):
+        return exc
+    if isinstance(exc, Exception):
+        raw_code = getattr(exc, "code", None)
+        raw_message = getattr(exc, "message", None)
+        raw_stage = getattr(exc, "stage", None)
+        raw_owner = getattr(exc, "owner", None)
+        raw_action = getattr(exc, "action", None)
+        if all(isinstance(value, str) and value.strip() for value in (raw_code, raw_message, raw_stage, raw_owner, raw_action)):
+            raw_summary = getattr(exc, "summary", None)
+            raw_detail = getattr(exc, "detail", None)
+            raw_context = getattr(exc, "context", None)
+            return PzError(
+                code=str(raw_code).strip(),
+                message=str(raw_message).strip(),
+                stage=str(raw_stage).strip(),
+                owner=str(raw_owner).strip(),
+                action=str(raw_action).strip(),
+                summary=str(raw_summary).strip() if isinstance(raw_summary, str) and raw_summary.strip() else None,
+                detail=str(raw_detail).strip() if isinstance(raw_detail, str) and raw_detail.strip() else None,
+                context=dict(raw_context) if isinstance(raw_context, dict) else None,
+            )
+    normalized_stage = _read_context_string(stage, field="stage", default="runtime")
+    normalized_owner = _read_context_string(owner, field="owner", default="runtime")
+    normalized_action = _read_context_string(action, field="action", default="unknown")
+    detail = str(exc) or exc.__class__.__name__
+    summary = _default_summary(stage=normalized_stage, action=normalized_action)
+    return PzError(
+        code=code,
+        message=summary,
+        stage=normalized_stage,
+        owner=normalized_owner,
+        action=normalized_action,
+        summary=summary,
+        detail=detail,
+    )

pz_core/core/events/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from .registry import EventDecl, EventHandlerDecl, EventRegistry
+
+__all__ = ["EventDecl", "EventHandlerDecl", "EventRegistry"]

pz_core/core/events/registry.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from pz_core.core.errors import PzError
+
+
+@dataclass(frozen=True, slots=True)
+class EventDecl:
+    name: str
+    owner: str
+    payload_schema: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class EventHandlerDecl:
+    event: str
+    import_path: str
+    owner: str
+
+
+@dataclass(frozen=True, slots=True)
+class EventRegistry:
+    events: tuple[EventDecl, ...] = ()
+    handlers: tuple[EventHandlerDecl, ...] = ()
+
+    def by_name(self) -> dict[str, EventDecl]:
+        return {event.name: event for event in self.events}
+
+    def handlers_for(self, event_name: str) -> tuple[EventHandlerDecl, ...]:
+        return tuple(handler for handler in self.handlers if handler.event == event_name)
+
+    def validate(self) -> None:
+        names = [event.name for event in self.events]
+        if len(names) != len(set(names)):
+            raise PzError(
+                code="PZ_EVENT_DUPLICATE_NAME",
+                message="EventRegistry contains duplicate event names.",
+                stage="events",
+                owner="core.events",
+                action="validate",
+            )
+        event_names = set(names)
+        unknown_events = sorted(
+            {handler.event for handler in self.handlers if handler.event not in event_names}
+        )
+        if unknown_events:
+            raise PzError(
+                code="PZ_EVENT_HANDLER_UNKNOWN_EVENT",
+                message="Handlers reference undeclared events: " + ", ".join(unknown_events),
+                stage="events",
+                owner="core.events",
+                action="validate",
+            )

pz_core/core/extensions/__init__.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from .registry import (
+    CliInvocationContext,
+    CliToolSpec,
+    ExtensionRegistry,
+    ExtensionSpec,
+    FormalExtensionSpec,
+    HostBuildContext,
+    HostBuildResult,
+    HostBuilderSpec,
+    InfraPatch,
+    InfraProviderContext,
+    InfraProviderSpec,
+    LifecycleContributionSpec,
+    PageProfileProviderSpec,
+    ResourceContributionSpec,
+    RuntimeManifestContributionSpec,
+    ProtocolExtensionSpec,
+    ProtocolRegistrationSpec,
+    SettingsPatch,
+    SettingsProviderContext,
+    SettingsProviderSpec,
+    WORKER_ROLE_KINDS,
+    WorkerRoleSpec,
+)
+
+__all__ = [
+    "CliInvocationContext",
+    "CliToolSpec",
+    "ExtensionRegistry",
+    "ExtensionSpec",
+    "FormalExtensionSpec",
+    "HostBuildContext",
+    "HostBuildResult",
+    "HostBuilderSpec",
+    "InfraPatch",
+    "InfraProviderContext",
+    "InfraProviderSpec",
+    "LifecycleContributionSpec",
+    "PageProfileProviderSpec",
+    "ResourceContributionSpec",
+    "RuntimeManifestContributionSpec",
+    "ProtocolExtensionSpec",
+    "ProtocolRegistrationSpec",
+    "SettingsPatch",
+    "SettingsProviderContext",
+    "SettingsProviderSpec",
+    "WORKER_ROLE_KINDS",
+    "WorkerRoleSpec",
+]