pz-cli 5.0.0__py3-none-any.whl

pz_core/runtime/registries/providers.py

@@ -0,0 +1,396 @@
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+from importlib import import_module
+import inspect
+from typing import Any
+from uuid import uuid4
+
+from pz_core.runtime.errors import PzError
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderDecl:
+    binding_id: str
+    capability: str
+    owner: str
+    scope: str = "runtime"
+    provider_path: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderBinding:
+    token: str
+    declaration: ProviderDecl
+    provider: object
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderActivationContext:
+    declaration: ProviderDecl
+    plan: Any
+    bindings: Any
+    host: object | None
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderDiagnostic:
+    binding_id: str
+    capability: str
+    owner: str
+    code: str
+    ok: bool
+    message: str
+
+
+@dataclass(slots=True)
+class ProviderRegistry:
+    declarations: tuple[ProviderDecl, ...] = ()
+    _bindings: dict[str, ProviderBinding] = field(default_factory=dict)
+    _failures: dict[str, ProviderDiagnostic] = field(default_factory=dict)
+    _diagnostics: list[ProviderDiagnostic] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        seen: set[str] = set()
+        for declaration in self.declarations:
+            if declaration.binding_id in seen:
+                raise PzError(
+                    code="PZ_PROVIDER_DUPLICATE_ID",
+                    message=f"Duplicate provider binding id '{declaration.binding_id}'.",
+                    stage="providers",
+                    owner=declaration.binding_id,
+                    action="compile_provider_declarations",
+                )
+            seen.add(declaration.binding_id)
+
+    def declared(self) -> tuple[ProviderDecl, ...]:
+        return self.declarations
+
+    def _read_required_capability(self, capability: object, *, action: str) -> str:
+        if not isinstance(capability, str) or not capability.strip():
+            raise PzError(
+                code="PZ_PROVIDER_CAPABILITY_INVALID",
+                message="provider capability must be a non-empty string.",
+                stage="providers",
+                owner="providers",
+                action=action,
+            )
+        return capability.strip()
+
+    def _read_required_binding_id(self, binding_id: object, *, action: str) -> str:
+        if not isinstance(binding_id, str) or not binding_id.strip():
+            raise PzError(
+                code="PZ_PROVIDER_BINDING_ID_INVALID",
+                message="provider binding_id must be a non-empty string.",
+                stage="providers",
+                owner="providers",
+                action=action,
+            )
+        return binding_id.strip()
+
+    def _read_required_owner(self, owner: object, *, action: str) -> str:
+        if not isinstance(owner, str) or not owner.strip():
+            raise PzError(
+                code="PZ_PROVIDER_OWNER_INVALID",
+                message="provider owner must be a non-empty string.",
+                stage="providers",
+                owner="providers",
+                action=action,
+            )
+        return owner.strip()
+
+    def _read_required_token(self, token: object, *, action: str) -> str:
+        if not isinstance(token, str) or not token.strip():
+            raise PzError(
+                code="PZ_PROVIDER_TOKEN_INVALID",
+                message="provider token must be a non-empty string.",
+                stage="providers",
+                owner="providers",
+                action=action,
+            )
+        return token.strip()
+
+    def declared_for(self, capability: str) -> tuple[ProviderDecl, ...]:
+        normalized = self._read_required_capability(capability, action="declared_for")
+        return tuple(item for item in self.declarations if item.capability == normalized)
+
+    def bindings(self) -> tuple[ProviderBinding, ...]:
+        return tuple(self._bindings.values())
+
+    def bindings_for(self, capability: str) -> tuple[ProviderBinding, ...]:
+        normalized = self._read_required_capability(capability, action="bindings_for")
+        return tuple(
+            binding for binding in self._bindings.values() if binding.declaration.capability == normalized
+        )
+
+    def diagnostics(self) -> tuple[ProviderDiagnostic, ...]:
+        return tuple(self._diagnostics)
+
+    def register(self, binding_id: str, provider: object) -> str:
+        normalized = self._read_required_binding_id(binding_id, action="register")
+        declaration = next(
+            (item for item in self.declarations if item.binding_id == normalized),
+            None,
+        )
+        if declaration is None:
+            raise PzError(
+                code="PZ_PROVIDER_DECL_MISSING",
+                message=f"Provider binding '{normalized}' is not declared in RuntimePlan.",
+                stage="providers",
+                owner=normalized or "providers",
+                action="register",
+            )
+        if any(
+            existing.declaration.binding_id == normalized for existing in self._bindings.values()
+        ):
+            raise PzError(
+                code="PZ_PROVIDER_ALREADY_REGISTERED",
+                message=f"Provider binding '{normalized}' is already registered.",
+                stage="providers",
+                owner=normalized,
+                action="register",
+            )
+        token = uuid4().hex
+        binding = ProviderBinding(token=token, declaration=declaration, provider=provider)
+        self._bindings[token] = binding
+        self._failures.pop(declaration.binding_id, None)
+        self._diagnostics.append(
+            ProviderDiagnostic(
+                binding_id=declaration.binding_id,
+                capability=declaration.capability,
+                owner=declaration.owner,
+                code="PZ_PROVIDER_REGISTERED",
+                ok=True,
+                message=f"Provider '{declaration.binding_id}' registered.",
+            )
+        )
+        return token
+
+    def unregister(self, token: str) -> bool:
+        binding = self._bindings.pop(self._read_required_token(token, action="unregister"), None)
+        if binding is None:
+            return False
+        self._diagnostics.append(
+            ProviderDiagnostic(
+                binding_id=binding.declaration.binding_id,
+                capability=binding.declaration.capability,
+                owner=binding.declaration.owner,
+                code="PZ_PROVIDER_UNREGISTERED",
+                ok=True,
+                message=f"Provider '{binding.declaration.binding_id}' unregistered.",
+            )
+        )
+        return True
+
+    def reset(self, *, owner: str | None = None) -> int:
+        if owner is None:
+            removed = len(self._bindings)
+            self._bindings.clear()
+            self._failures.clear()
+            self._diagnostics.clear()
+            return removed
+        target = self._read_required_owner(owner, action="reset")
+        tokens = [
+            token
+            for token, binding in self._bindings.items()
+            if binding.declaration.owner == target
+        ]
+        for token in tokens:
+            self.unregister(token)
+        failed_ids = [
+            binding_id
+            for binding_id, diagnostic in self._failures.items()
+            if diagnostic.owner == target
+        ]
+        for binding_id in failed_ids:
+            self._failures.pop(binding_id, None)
+        return len(tokens)
+
+    def failed_for(self, capability: str) -> tuple[ProviderDiagnostic, ...]:
+        normalized = self._read_required_capability(capability, action="failed_for")
+        return tuple(
+            diagnostic
+            for diagnostic in self._failures.values()
+            if diagnostic.capability == normalized
+        )
+
+    def activate_declared(
+        self,
+        *,
+        plan: Any,
+        bindings: Any,
+        host: object | None = None,
+        owner: str | None = None,
+    ) -> int:
+        activated = 0
+        owner_filter = self._read_required_owner(owner, action="activate_declared") if owner is not None else None
+        for declaration in self.declarations:
+            if owner_filter is not None and declaration.owner != owner_filter:
+                continue
+            if declaration.provider_path is None:
+                continue
+            if any(
+                existing.declaration.binding_id == declaration.binding_id
+                for existing in self._bindings.values()
+            ):
+                continue
+            provider = self._build_provider(
+                declaration,
+                context=ProviderActivationContext(
+                    declaration=declaration,
+                    plan=plan,
+                    bindings=bindings,
+                    host=host,
+                ),
+            )
+            if provider is None:
+                continue
+            self.register(declaration.binding_id, provider)
+            activated += 1
+        return activated
+
+    def _build_provider(
+        self,
+        declaration: ProviderDecl,
+        *,
+        context: ProviderActivationContext,
+    ) -> object | None:
+        provider_path = declaration.provider_path
+        if provider_path is None:
+            return None
+        module_name, _, attr_name = provider_path.partition(":")
+        if not module_name or not attr_name:
+            self._record_failure(
+                declaration,
+                code="PZ_PROVIDER_PATH_INVALID",
+                message=(
+                    f"Provider binding '{declaration.binding_id}' has invalid provider_path "
+                    f"'{provider_path}'."
+                ),
+            )
+            return None
+        try:
+            module = import_module(module_name)
+            factory = getattr(module, attr_name)
+        except Exception as exc:
+            self._record_failure(
+                declaration,
+                code="PZ_PROVIDER_IMPORT_FAILED",
+                message=(
+                    f"Provider binding '{declaration.binding_id}' import failed: {exc}"
+                ),
+            )
+            return None
+        if not callable(factory):
+            self._record_failure(
+                declaration,
+                code="PZ_PROVIDER_FACTORY_INVALID",
+                message=f"Provider factory '{provider_path}' is not callable.",
+            )
+            return None
+        try:
+            signature = inspect.signature(factory)
+            param_count = len(signature.parameters)
+            if param_count == 0:
+                result = factory()
+            elif param_count == 1:
+                result = factory(context)
+            else:
+                result = factory(context.host, context)
+            if inspect.isawaitable(result):
+                try:
+                    asyncio.get_running_loop()
+                except RuntimeError:
+                    result = asyncio.run(result)
+                else:
+                    raise PzError(
+                        code="PZ_PROVIDER_ASYNC_IN_RUNNING_LOOP",
+                        message=(
+                            f"Provider '{declaration.binding_id}' returned an awaitable inside "
+                            "a running loop."
+                        ),
+                        stage="providers",
+                        owner=declaration.owner,
+                        action="activate_declared",
+                    )
+        except PzError as exc:
+            self._record_failure(
+                declaration,
+                code=exc.code,
+                message=exc.message,
+            )
+            return None
+        except Exception as exc:
+            self._record_failure(
+                declaration,
+                code="PZ_PROVIDER_FACTORY_FAILED",
+                message=(
+                    f"Provider binding '{declaration.binding_id}' factory failed: {exc}"
+                ),
+            )
+            return None
+        return result
+
+    def _record_failure(
+        self,
+        declaration: ProviderDecl,
+        *,
+        code: str,
+        message: str,
+    ) -> None:
+        diagnostic = ProviderDiagnostic(
+            binding_id=declaration.binding_id,
+            capability=declaration.capability,
+            owner=declaration.owner,
+            code=code,
+            ok=False,
+            message=message,
+        )
+        self._failures[declaration.binding_id] = diagnostic
+        self._diagnostics.append(diagnostic)
+
+    def require(self, capability: str) -> object:
+        normalized_capability = self._read_required_capability(capability, action="require")
+        bindings = self.bindings_for(normalized_capability)
+        if not bindings:
+            failures = self.failed_for(normalized_capability)
+            if failures:
+                latest = failures[-1]
+                raise PzError(
+                    code=latest.code,
+                    message=latest.message,
+                    stage="providers",
+                    owner=latest.owner,
+                    action="require",
+                )
+            raise PzError(
+                code="PZ_PROVIDER_NOT_READY",
+                message=f"No provider registered for capability '{normalized_capability}'.",
+                stage="providers",
+                owner=normalized_capability,
+                action="require",
+            )
+        if len(bindings) > 1:
+            order = {decl.binding_id: index for index, decl in enumerate(self.declarations)}
+            bindings = tuple(
+                sorted(
+                    bindings,
+                    key=lambda item: (
+                        int(order.get(item.declaration.binding_id, 10**9)),
+                        str(item.declaration.owner),
+                        str(item.declaration.binding_id),
+                    ),
+                )
+            )
+        return bindings[0].provider
+
+    def status(self, capability: str) -> str:
+        normalized_capability = self._read_required_capability(capability, action="status")
+        if self.bindings_for(normalized_capability):
+            return "ready"
+        if self.failed_for(normalized_capability):
+            return "unavailable"
+        if self.declared_for(normalized_capability):
+            return "enabled"
+        return "disabled"