pz-cli 5.0.0__py3-none-any.whl

pz_core/runtime/__init__.py

@@ -0,0 +1,229 @@
+from __future__ import annotations
+
+from importlib import import_module
+from typing import TYPE_CHECKING
+
+__all__ = [
+    "AppLifecycleState",
+    "ApplicationRuntime",
+    "CacheFacade",
+    "DatabaseFacade",
+    "EventBusFacade",
+    "EventDispatchResult",
+    "EventDispatchTicket",
+    "EventSubscription",
+    "HealthFacade",
+    "MailFacade",
+    "ObservabilityFacade",
+    "ProviderFacade",
+    "ResolvedSettings",
+    "SettingsSnapshot",
+    "RuntimePlan",
+    "RuntimeBindings",
+    "ResourceFacade",
+    "RuntimePresignInfo",
+    "RuntimeStoragePort",
+    "RuntimeStoredObject",
+    "StorageFacade",
+    "StorageClient",
+    "publish",
+    "publish_nowait",
+    "subscribe",
+    "get_bindings",
+    "get_runtime",
+    "get_storage",
+    "WorkerRuntime",
+    "WorkerSession",
+    "WorkerInvocation",
+    "build_worker_status",
+    "compile_runtime_plan",
+    "active_runtime_plan",
+    "current_runtime_plan",
+    "resolve_settings",
+    "load_local_default_settings",
+    "load_local_default_settings_chain",
+    "build_local_default_settings",
+    "build_local_default_settings_chain",
+    "to_jsonable",
+    "discover_leaf_app_packages",
+    "compile_runtime_bindings",
+    "create_application_runtime",
+    "apply_runtime_middlewares",
+    "create_worker_runtime",
+    "create_application_runtime_from_plan",
+    "load_runtime_plan_snapshot",
+    "write_runtime_plan_snapshot",
+    "write_runtime_plan_snapshot_if_requested",
+    "RUNTIME_PLAN_SNAPSHOT_ENV",
+    "RUNTIME_PLAN_SNAPSHOT_ID_ENV",
+    "resolve_package_root",
+    "run_worker_entry",
+    "CapabilityRegistry",
+    "CapabilityState",
+    "PzError",
+    "as_pz_error",
+    "EventRegistry",
+    "ExtensionRegistry",
+    "LifecycleState",
+    "activate_runtime_plan",
+    "activate_runtime_plan_async",
+    "bind_runtime_plan",
+    "compile_lifecycle_state",
+    "shutdown_runtime_plan",
+    "shutdown_runtime_plan_async",
+]
+
+
+if TYPE_CHECKING:
+    from pz_core.assembly.settings import SettingsSnapshot
+    from pz_core.core.events import EventRegistry
+    from pz_core.core.extensions import ExtensionRegistry
+    from .errors import PzError, as_pz_error
+    from .bindings import RuntimeBindings, compile_runtime_bindings
+    from .facades import (
+        CacheFacade,
+        DatabaseFacade,
+        EventBusFacade,
+        EventDispatchResult,
+        EventDispatchTicket,
+        EventSubscription,
+        HealthFacade,
+        MailFacade,
+        ObservabilityFacade,
+        ProviderFacade,
+        ResourceFacade,
+        RuntimePresignInfo,
+        RuntimeStoragePort,
+        RuntimeStoredObject,
+        StorageClient,
+        StorageFacade,
+        get_storage,
+    )
+    from .events import publish, publish_nowait, subscribe
+    from .http import (
+        ApplicationRuntime,
+        apply_runtime_middlewares,
+        create_application_runtime,
+        create_application_runtime_from_plan,
+    )
+    from .lifecycle import (
+        AppLifecycleState,
+        LifecycleState,
+        activate_runtime_plan,
+        activate_runtime_plan_async,
+        bind_runtime_plan,
+        compile_lifecycle_state,
+        shutdown_runtime_plan,
+        shutdown_runtime_plan_async,
+    )
+    from .plan import RuntimePlan, compile_runtime_plan
+    from .plan_snapshot import (
+        RUNTIME_PLAN_SNAPSHOT_ENV,
+        RUNTIME_PLAN_SNAPSHOT_ID_ENV,
+        load_runtime_plan_snapshot,
+        write_runtime_plan_snapshot,
+        write_runtime_plan_snapshot_if_requested,
+    )
+    from .plan_context import active_runtime_plan, current_runtime_plan
+    from .discovery import discover_leaf_app_packages, resolve_package_root
+    from .settings import (
+        ResolvedSettings,
+        build_local_default_settings,
+        build_local_default_settings_chain,
+        load_local_default_settings,
+        load_local_default_settings_chain,
+        resolve_settings,
+    )
+    from .json_safe import to_jsonable
+    from .access import get_bindings, get_runtime
+    from .registries import CapabilityRegistry, CapabilityState
+    from .worker import (
+        WorkerInvocation,
+        WorkerRuntime,
+        WorkerSession,
+        build_worker_status,
+        create_worker_runtime,
+        run_worker_entry,
+    )
+
+
+_EXPORTS = {
+    "SettingsSnapshot": ("pz_core.assembly.settings", "SettingsSnapshot"),
+    "EventRegistry": ("pz_core.core.events", "EventRegistry"),
+    "ExtensionRegistry": ("pz_core.core.extensions", "ExtensionRegistry"),
+    "RuntimeBindings": (".bindings", "RuntimeBindings"),
+    "compile_runtime_bindings": (".bindings", "compile_runtime_bindings"),
+    "CacheFacade": (".facades", "CacheFacade"),
+    "DatabaseFacade": (".facades", "DatabaseFacade"),
+    "EventBusFacade": (".facades", "EventBusFacade"),
+    "EventDispatchResult": (".facades", "EventDispatchResult"),
+    "EventDispatchTicket": (".facades", "EventDispatchTicket"),
+    "EventSubscription": (".facades", "EventSubscription"),
+    "HealthFacade": (".facades", "HealthFacade"),
+    "MailFacade": (".facades", "MailFacade"),
+    "ObservabilityFacade": (".facades", "ObservabilityFacade"),
+    "ProviderFacade": (".facades", "ProviderFacade"),
+    "ResourceFacade": (".facades", "ResourceFacade"),
+    "RuntimePresignInfo": (".facades", "RuntimePresignInfo"),
+    "RuntimeStoragePort": (".facades", "RuntimeStoragePort"),
+    "RuntimeStoredObject": (".facades", "RuntimeStoredObject"),
+    "StorageFacade": (".facades", "StorageFacade"),
+    "StorageClient": (".facades", "StorageClient"),
+    "get_storage": (".facades", "get_storage"),
+    "publish": (".events", "publish"),
+    "publish_nowait": (".events", "publish_nowait"),
+    "subscribe": (".events", "subscribe"),
+    "get_bindings": (".access", "get_bindings"),
+    "get_runtime": (".access", "get_runtime"),
+    "ApplicationRuntime": (".http", "ApplicationRuntime"),
+    "apply_runtime_middlewares": (".http", "apply_runtime_middlewares"),
+    "create_application_runtime": (".http", "create_application_runtime"),
+    "create_application_runtime_from_plan": (".http", "create_application_runtime_from_plan"),
+    "RUNTIME_PLAN_SNAPSHOT_ENV": (".plan_snapshot", "RUNTIME_PLAN_SNAPSHOT_ENV"),
+    "RUNTIME_PLAN_SNAPSHOT_ID_ENV": (".plan_snapshot", "RUNTIME_PLAN_SNAPSHOT_ID_ENV"),
+    "load_runtime_plan_snapshot": (".plan_snapshot", "load_runtime_plan_snapshot"),
+    "write_runtime_plan_snapshot": (".plan_snapshot", "write_runtime_plan_snapshot"),
+    "write_runtime_plan_snapshot_if_requested": (".plan_snapshot", "write_runtime_plan_snapshot_if_requested"),
+    "AppLifecycleState": (".lifecycle", "AppLifecycleState"),
+    "LifecycleState": (".lifecycle", "LifecycleState"),
+    "activate_runtime_plan": (".lifecycle", "activate_runtime_plan"),
+    "activate_runtime_plan_async": (".lifecycle", "activate_runtime_plan_async"),
+    "bind_runtime_plan": (".lifecycle", "bind_runtime_plan"),
+    "compile_lifecycle_state": (".lifecycle", "compile_lifecycle_state"),
+    "shutdown_runtime_plan": (".lifecycle", "shutdown_runtime_plan"),
+    "shutdown_runtime_plan_async": (".lifecycle", "shutdown_runtime_plan_async"),
+    "RuntimePlan": (".plan", "RuntimePlan"),
+    "compile_runtime_plan": (".plan", "compile_runtime_plan"),
+    "active_runtime_plan": (".plan_context", "active_runtime_plan"),
+    "current_runtime_plan": (".plan_context", "current_runtime_plan"),
+    "discover_leaf_app_packages": (".discovery", "discover_leaf_app_packages"),
+    "resolve_package_root": (".discovery", "resolve_package_root"),
+    "ResolvedSettings": (".settings", "ResolvedSettings"),
+    "resolve_settings": (".settings", "resolve_settings"),
+    "CapabilityRegistry": (".registries", "CapabilityRegistry"),
+    "CapabilityState": (".registries", "CapabilityState"),
+    "load_local_default_settings": (".settings", "load_local_default_settings"),
+    "load_local_default_settings_chain": (".settings", "load_local_default_settings_chain"),
+    "build_local_default_settings": (".settings", "build_local_default_settings"),
+    "build_local_default_settings_chain": (".settings", "build_local_default_settings_chain"),
+    "to_jsonable": (".json_safe", "to_jsonable"),
+    "PzError": (".errors", "PzError"),
+    "as_pz_error": (".errors", "as_pz_error"),
+    "WorkerInvocation": (".worker", "WorkerInvocation"),
+    "WorkerRuntime": (".worker", "WorkerRuntime"),
+    "WorkerSession": (".worker", "WorkerSession"),
+    "build_worker_status": (".worker", "build_worker_status"),
+    "create_worker_runtime": (".worker", "create_worker_runtime"),
+    "run_worker_entry": (".worker", "run_worker_entry"),
+}
+
+
+def __getattr__(name: str):
+    try:
+        module_name, attr_name = _EXPORTS[name]
+    except KeyError as exc:
+        raise AttributeError(name) from exc
+    module = import_module(module_name, __name__)
+    value = getattr(module, attr_name)
+    globals()[name] = value
+    return value

pz_core/runtime/access.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from pz_core.runtime.errors import PzError
+
+if TYPE_CHECKING:
+    from pz_core.runtime.bindings import RuntimeBindings
+
+
+def _runtime_from_request(request: Any) -> Any | None:
+    candidates = [
+        request,
+        getattr(request, "state", None),
+        getattr(request, "app", None),
+    ]
+    app = getattr(request, "app", None)
+    if app is not None:
+        candidates.append(getattr(app, "state", None))
+    for candidate in candidates:
+        runtime = getattr(candidate, "pz_runtime", None) if candidate is not None else None
+        if runtime is not None:
+            return runtime
+    return None
+
+
+def _validate_runtime(runtime: object) -> object:
+    if runtime is None:
+        raise PzError(
+            code="PZ_RUNTIME_INVALID",
+            message="runtime must be provided when configured.",
+            stage="runtime",
+            owner="runtime.access",
+            action="get_runtime",
+        )
+    if not hasattr(runtime, "bindings"):
+        raise PzError(
+            code="PZ_RUNTIME_INVALID",
+            message="runtime must expose bindings when configured.",
+            stage="runtime",
+            owner="runtime.access",
+            action="get_runtime",
+        )
+    return runtime
+
+
+def get_runtime(*, request: Any | None = None, runtime: Any | None = None):
+    if runtime is not None:
+        return _validate_runtime(runtime)
+    if request is not None:
+        request_runtime = _runtime_from_request(request)
+        if request_runtime is not None:
+            return request_runtime
+    raise PzError(
+        code="PZ_RUNTIME_CONTEXT_MISSING",
+        message=(
+            "Runtime access requires an explicit runtime or a request bound to the current runtime."
+        ),
+        stage="runtime",
+        owner="runtime.access",
+        action="get_runtime",
+    )
+
+
+def get_bindings(
+    *,
+    request: Any | None = None,
+    runtime: Any | None = None,
+    bindings: "RuntimeBindings | None" = None,
+):
+    if bindings is not None:
+        from pz_core.runtime.bindings import RuntimeBindings
+
+        if not isinstance(bindings, RuntimeBindings):
+            raise PzError(
+                code="PZ_RUNTIME_BINDINGS_INVALID",
+                message="bindings must be a RuntimeBindings instance when configured.",
+                stage="runtime",
+                owner="runtime.access",
+                action="get_bindings",
+            )
+        return bindings
+    return get_runtime(request=request, runtime=runtime).bindings
+
+
+__all__ = ["get_bindings", "get_runtime"]

pz_core/runtime/adapters/__init__.py

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

pz_core/runtime/adapters/base.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from pz_core.runtime.bindings import RuntimeBindings
+from pz_core.runtime.lifecycle import LifecycleState
+from pz_core.runtime.plan import RuntimePlan
+
+AdapterKind = Literal["cli", "http", "worker"]
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeAdapter:
+    kind: AdapterKind
+    plan: RuntimePlan
+    state: LifecycleState
+    bindings: RuntimeBindings

pz_core/runtime/asyncio_bridge.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import asyncio
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any
+
+
+def run_coro_blocking(awaitable: Any) -> Any:
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        return asyncio.run(awaitable)
+    with ThreadPoolExecutor(max_workers=1, thread_name_prefix="pz_startup") as executor:
+        future = executor.submit(asyncio.run, awaitable)
+        return future.result()
+
+
+__all__ = ["run_coro_blocking"]

pz_core/runtime/bindings/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from .container import RuntimeBindings, compile_runtime_bindings
+
+__all__ = ["RuntimeBindings", "compile_runtime_bindings"]

pz_core/runtime/bindings/container.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from pz_core.runtime.facades import (
+    CacheFacade,
+    DatabaseFacade,
+    EventBusFacade,
+    HealthFacade,
+    MailFacade,
+    ObservabilityFacade,
+    ProviderFacade,
+    ResourceFacade,
+    StorageFacade,
+)
+from pz_core.runtime.lifecycle import LifecycleState, bind_runtime_plan
+from pz_core.runtime.plan import RuntimePlan
+from pz_core.runtime.registries import ProviderRegistry
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeBindings:
+    cache: CacheFacade
+    database: DatabaseFacade
+    events: EventBusFacade
+    health: HealthFacade
+    mail: MailFacade
+    observability: ObservabilityFacade
+    providers: ProviderFacade
+    resources: ResourceFacade
+    storage: StorageFacade
+
+
+def compile_runtime_bindings(
+    plan: RuntimePlan,
+    state: LifecycleState | None = None,
+) -> RuntimeBindings:
+    lifecycle = state or bind_runtime_plan(plan)
+    providers = ProviderFacade(ProviderRegistry(plan.provider_declarations))
+    return RuntimeBindings(
+        cache=CacheFacade(plan, providers),
+        database=DatabaseFacade(plan, providers),
+        events=EventBusFacade(plan.event_registry),
+        health=HealthFacade(plan, lifecycle, providers=providers),
+        mail=MailFacade(plan, providers),
+        observability=ObservabilityFacade(plan, providers),
+        providers=providers,
+        resources=ResourceFacade(plan.resource_manifest, providers),
+        storage=StorageFacade(plan, providers),
+    )

pz_core/runtime/cli/__init__.py

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

pz_core/runtime/cli/_args.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import argparse
+from collections.abc import Sequence
+
+from pz_core.runtime.errors import PzError
+
+
+def json_output_requested(argv: Sequence[object] | None) -> bool:
+    if argv is None:
+        return False
+    return any(isinstance(item, str) and item in {"--json", "-j"} for item in argv)
+
+
+def normalize_cli_argv(
+    argv: Sequence[object] | None,
+    *,
+    code: str,
+    stage: str,
+    owner: str,
+    action: str,
+) -> list[str]:
+    if argv is None:
+        return []
+    normalized: list[str] = []
+    for index, item in enumerate(argv):
+        if not isinstance(item, str) or not item.strip():
+            raise PzError(
+                code=code,
+                message=f"CLI argv entry at index {index} must be a non-empty string.",
+                stage=stage,
+                owner=owner,
+                action=action,
+            )
+        normalized.append(item)
+    return normalized
+
+
+class PzArgumentParser(argparse.ArgumentParser):
+    def __init__(
+        self,
+        *args,
+        error_code: str = "PZ_CLI_ARGUMENTS_INVALID",
+        error_stage: str = "cli",
+        error_owner: str = "runtime.cli",
+        error_action: str = "parse_args",
+        **kwargs,
+    ) -> None:
+        super().__init__(*args, **kwargs)
+        self._error_code = error_code
+        self._error_stage = error_stage
+        self._error_owner = error_owner
+        self._error_action = error_action
+
+    def error(self, message: str) -> None:
+        raise PzError(
+            code=self._error_code,
+            message=message,
+            stage=self._error_stage,
+            owner=self._error_owner,
+            action=self._error_action,
+            summary="CLI arguments are invalid.",
+            detail=message,
+        )
+
+
+__all__ = ["PzArgumentParser", "json_output_requested", "normalize_cli_argv"]