pz-cli 5.0.0__py3-none-any.whl

pz_core/runtime/environment_integrity.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from importlib import metadata as importlib_metadata
+from pathlib import Path
+import re
+
+from pz_core.runtime.errors import PzError
+
+
+PROJECT_CONFIG_NAME = "pz.jsonc"
+PROJECT_ENV_CONFIG_PATTERN = "pz.{environment}.jsonc"
+PZ_ENV_PREFIX = "PZ_"
+_FORMAL_ENVIRONMENTS = ("develop", "test", "product")
+
+_LEGACY_STEM = "pyz" + "za"
+_LEGACY_ENV_PREFIX = _LEGACY_STEM.upper() + "_"
+_LEGACY_APP_PREFIX = _LEGACY_STEM + "_"
+_LEGACY_DISTRIBUTION_PREFIX = _LEGACY_STEM + "-"
+_RETIRED_BASE_DISTRIBUTIONS = frozenset(
+    {"pz-core", "pz-settings-center", "pz-foundation", "pz-contrib"}
+)
+
+
+def _canonicalize_distribution_name(value: object) -> str:
+    return re.sub(r"[-_.]+", "-", str(value or "").strip()).lower()
+
+
+def _distribution_name(distribution: importlib_metadata.Distribution) -> str:
+    metadata = getattr(distribution, "metadata", None)
+    raw_name = metadata.get("Name") if metadata is not None and hasattr(metadata, "get") else None
+    if raw_name is None:
+        raw_name = getattr(distribution, "name", None)
+    return _canonicalize_distribution_name(raw_name)
+
+
+def validate_process_environment(environ: Mapping[str, str]) -> None:
+    """Reject every framework-owned v4 environment key."""
+
+    legacy_keys = sorted(
+        str(key)
+        for key in environ
+        if str(key).startswith(_LEGACY_ENV_PREFIX)
+    )
+    if not legacy_keys:
+        return
+    raise PzError(
+        code="PZ_LEGACY_ENV_UNSUPPORTED",
+        message=(
+            "Legacy framework environment keys are not supported. "
+            f"Use {PZ_ENV_PREFIX}* keys only."
+        ),
+        stage="environment",
+        owner="runtime.environment_integrity",
+        action="validate_process_environment",
+        detail=", ".join(legacy_keys),
+    )
+
+
+def validate_installed_distributions(
+    distributions: Iterable[importlib_metadata.Distribution],
+) -> None:
+    """Reject every installed v4 framework distribution."""
+
+    unsupported_names = sorted(
+        {
+            name
+            for distribution in distributions
+            if (name := _distribution_name(distribution))
+            and (
+                name == _LEGACY_STEM
+                or name.startswith(_LEGACY_DISTRIBUTION_PREFIX)
+                or name in _RETIRED_BASE_DISTRIBUTIONS
+            )
+        }
+    )
+    if not unsupported_names:
+        return
+    raise PzError(
+        code="PZ_ENVIRONMENT_MIXED_GENERATIONS",
+        message=(
+            "The current Python environment contains unsupported legacy or "
+            "retired split-wheel distributions. Recreate it with pz-cli==5.0.0."
+        ),
+        stage="environment",
+        owner="runtime.environment_integrity",
+        action="validate_installed_distributions",
+        detail=", ".join(unsupported_names),
+    )
+
+
+def validate_installed_app_identities(app_ids: Iterable[object]) -> None:
+    legacy_app_ids = sorted(
+        {
+            value
+            for raw_value in app_ids
+            if isinstance(raw_value, str)
+            and (value := raw_value.strip())
+            and any(part.startswith(_LEGACY_APP_PREFIX) for part in value.split("."))
+        }
+    )
+    if not legacy_app_ids:
+        return
+    raise PzError(
+        code="PZ_LEGACY_APP_ID_UNSUPPORTED",
+        message="installed_apps contains unsupported v4 app identities.",
+        stage="apps",
+        owner="runtime.environment_integrity",
+        action="validate_installed_app_identities",
+        detail=", ".join(legacy_app_ids),
+    )
+
+
+def validate_project_config_identity(project_dir: str | Path) -> None:
+    root = Path(project_dir).expanduser().resolve()
+    legacy_paths = [root / (_LEGACY_STEM + ".jsonc")]
+    legacy_paths.extend(
+        root / f"{_LEGACY_STEM}.{environment}.jsonc"
+        for environment in _FORMAL_ENVIRONMENTS
+    )
+    existing = sorted({path.resolve() for path in legacy_paths if path.is_file()})
+    if not existing:
+        return
+    raise PzError(
+        code="PZ_PROJECT_CONFIG_LEGACY_UNSUPPORTED",
+        message=(
+            "Legacy project configuration files are not supported. "
+            f"Use {PROJECT_CONFIG_NAME} and {PROJECT_ENV_CONFIG_PATTERN}."
+        ),
+        stage="project",
+        owner="runtime.environment_integrity",
+        action="validate_project_config_identity",
+        detail=", ".join(path.name for path in existing),
+    )
+
+
+def validate_current_environment(
+    environ: Mapping[str, str],
+    *,
+    distributions: Iterable[importlib_metadata.Distribution] | None = None,
+) -> None:
+    validate_process_environment(environ)
+    validate_installed_distributions(
+        importlib_metadata.distributions() if distributions is None else distributions
+    )
+
+
+__all__ = [
+    "PROJECT_CONFIG_NAME",
+    "PROJECT_ENV_CONFIG_PATTERN",
+    "PZ_ENV_PREFIX",
+    "validate_current_environment",
+    "validate_installed_app_identities",
+    "validate_installed_distributions",
+    "validate_process_environment",
+    "validate_project_config_identity",
+]

pz_core/runtime/errors.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from pz_core.core.errors import PzError, as_pz_error
+
+__all__ = ["PzError", "as_pz_error"]

pz_core/runtime/events.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pz_core.runtime.errors import PzError
+from pz_core.runtime.access import get_bindings
+from pz_core.runtime.bindings import RuntimeBindings
+
+
+def _resolve_runtime_bindings(
+    *,
+    bindings: RuntimeBindings | None = None,
+    request: Any | None = None,
+    runtime: Any | None = None,
+) -> RuntimeBindings:
+    if bindings is not None:
+        if not isinstance(bindings, RuntimeBindings):
+            raise PzError(
+                code="PZ_RUNTIME_BINDINGS_INVALID",
+                message="runtime events bindings must be a RuntimeBindings instance.",
+                stage="events",
+                owner="runtime.events",
+                action="resolve_bindings",
+            )
+        return bindings
+    return get_bindings(request=request, runtime=runtime)
+
+
+def publish_nowait(
+    event_name: str,
+    payload: dict[str, Any] | None = None,
+    *,
+    owner: str = "pz_core.runtime.events",
+    bindings: RuntimeBindings | None = None,
+    request: Any | None = None,
+    runtime: Any | None = None,
+):
+    resolved_bindings = _resolve_runtime_bindings(
+        bindings=bindings,
+        request=request,
+        runtime=runtime,
+    )
+    return resolved_bindings.events.publish_nowait(event_name, payload, owner=owner)
+
+
+async def publish(
+    event_name: str,
+    payload: dict[str, Any] | None = None,
+    *,
+    owner: str = "pz_core.runtime.events",
+    bindings: RuntimeBindings | None = None,
+    request: Any | None = None,
+    runtime: Any | None = None,
+):
+    resolved_bindings = _resolve_runtime_bindings(
+        bindings=bindings,
+        request=request,
+        runtime=runtime,
+    )
+    return await resolved_bindings.events.publish(event_name, payload, owner=owner)
+
+
+def subscribe(
+    event_name: str,
+    handler,
+    *,
+    owner: str | None = None,
+    wildcard: bool = False,
+    bindings: RuntimeBindings | None = None,
+    request: Any | None = None,
+    runtime: Any | None = None,
+):
+    normalized_owner = owner or getattr(handler, "__module__", "pz_core.runtime.events")
+    resolved_bindings = _resolve_runtime_bindings(
+        bindings=bindings,
+        request=request,
+        runtime=runtime,
+    )
+    return resolved_bindings.events.subscribe(
+        event_name,
+        handler,
+        owner=normalized_owner,
+        wildcard=wildcard,
+    )
+
+
+__all__ = ["publish", "publish_nowait", "subscribe"]

pz_core/runtime/facades/__init__.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from .cache import CacheFacade
+from .database import DatabaseFacade
+from .events import EventBusFacade, EventDispatchResult, EventDispatchTicket, EventSubscription
+from .health import HealthFacade
+from .mail import MailFacade
+from .observability import ObservabilityFacade
+from .providers import ProviderFacade
+from .resources import ResourceFacade
+from .storage import StorageFacade
+from .storage import (
+    RuntimePresignInfo,
+    RuntimeStoragePort,
+    RuntimeStoredObject,
+    StorageClient,
+    get_storage,
+)
+
+__all__ = [
+    "CacheFacade",
+    "DatabaseFacade",
+    "EventBusFacade",
+    "EventDispatchResult",
+    "EventDispatchTicket",
+    "EventSubscription",
+    "HealthFacade",
+    "MailFacade",
+    "ObservabilityFacade",
+    "ProviderFacade",
+    "ResourceFacade",
+    "StorageFacade",
+    "RuntimePresignInfo",
+    "RuntimeStoragePort",
+    "RuntimeStoredObject",
+    "StorageClient",
+    "get_storage",
+]

pz_core/runtime/facades/_capabilities.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from pz_core.runtime.facades.providers import ProviderFacade
+from pz_core.runtime.plan import RuntimePlan
+from pz_core.runtime.registries import CapabilityStatus
+from pz_core.runtime.errors import PzError
+
+
+def merged_capability_status(
+    plan: RuntimePlan,
+    providers: ProviderFacade,
+    capability: str,
+) -> CapabilityStatus:
+    if not isinstance(plan, RuntimePlan):
+        raise PzError(
+            code="PZ_CAPABILITY_PLAN_INVALID",
+            message="capability status merge requires a RuntimePlan instance.",
+            stage="capabilities",
+            owner="runtime.capabilities",
+            action="merged_capability_status",
+        )
+    if not hasattr(providers, "declared_for") or not hasattr(providers, "status"):
+        raise PzError(
+            code="PZ_CAPABILITY_PROVIDERS_INVALID",
+            message="capability status merge requires providers with declared_for() and status().",
+            stage="capabilities",
+            owner="runtime.capabilities",
+            action="merged_capability_status",
+        )
+    if not isinstance(capability, str) or not capability.strip():
+        raise PzError(
+            code="PZ_CAPABILITY_NAME_INVALID",
+            message="capability name must be a non-empty string.",
+            stage="capabilities",
+            owner="runtime.capabilities",
+            action="merged_capability_status",
+        )
+    normalized = capability.strip()
+    base = plan.capability_registry.get(normalized)
+    base_status: CapabilityStatus = base.status if base is not None else "disabled"
+    if not providers.declared_for(normalized):
+        return base_status
+    provider_status = providers.status(normalized)
+    if provider_status == "disabled":
+        return base_status
+    return provider_status

pz_core/runtime/facades/cache.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pz_core.runtime.errors import PzError
+from pz_core.infra.kv import CacheClientFactory, CachePort
+from pz_core.runtime.facades._capabilities import merged_capability_status
+from pz_core.runtime.facades.providers import ProviderFacade
+from pz_core.runtime.plan import RuntimePlan
+from pz_core.runtime.registries import CapabilityStatus
+
+
+def _require_cache_key(key: str, *, action: str) -> str:
+    if not isinstance(key, str) or not key.strip():
+        raise PzError(
+            code="PZ_CACHE_KEY_INVALID",
+            message="Cache key must be a non-empty string.",
+            stage="cache",
+            owner="runtime.cache",
+            action=action,
+        )
+    return key
+
+
+def _require_cache_ttl(ttl: int | None, *, action: str) -> int | None:
+    if ttl is None:
+        return None
+    if isinstance(ttl, bool) or not isinstance(ttl, int) or ttl <= 0:
+        raise PzError(
+            code="PZ_CACHE_TTL_INVALID",
+            message="Cache ttl must be a positive integer when configured.",
+            stage="cache",
+            owner="runtime.cache",
+            action=action,
+        )
+    return ttl
+
+
+class CacheFacade:
+    def __init__(self, plan: RuntimePlan, providers: ProviderFacade) -> None:
+        if not isinstance(plan, RuntimePlan):
+            raise PzError(
+                code="PZ_CACHE_PLAN_INVALID",
+                message="CacheFacade requires a RuntimePlan instance.",
+                stage="cache",
+                owner="runtime.cache",
+                action="bind_cache_facade",
+            )
+        if not hasattr(providers, "require"):
+            raise PzError(
+                code="PZ_CACHE_PROVIDERS_INVALID",
+                message="CacheFacade providers must expose require().",
+                stage="cache",
+                owner="runtime.cache",
+                action="bind_cache_facade",
+            )
+        self._plan = plan
+        self._providers = providers
+
+    def status(self) -> CapabilityStatus:
+        return merged_capability_status(self._plan, self._providers, "cache")
+
+    def _cache(self) -> CachePort:
+        provider = self._providers.require("cache")
+        if isinstance(provider, CachePort):
+            return provider
+        if isinstance(provider, CacheClientFactory):
+            return provider.create_cache()
+        raise PzError(
+            code="PZ_CACHE_PROVIDER_INVALID",
+            message="Registered cache provider does not implement CachePort or CacheClientFactory.",
+            stage="cache",
+            owner="infra.cache",
+            action="resolve_cache",
+        )
+
+    def get(self, key: str) -> Any:
+        key = _require_cache_key(key, action="get")
+        return self._cache().get(key)
+
+    def set(self, key: str, value: object, *, ttl: int | None = None) -> None:
+        key = _require_cache_key(key, action="set")
+        ttl = _require_cache_ttl(ttl, action="set")
+        self._cache().set(key, value, ttl_seconds=ttl)
+
+    def delete(self, key: str) -> None:
+        key = _require_cache_key(key, action="delete")
+        self._cache().delete(key)
+
+    def lock(self, key: str, *, ttl: int | None = None) -> object:
+        key = _require_cache_key(key, action="lock")
+        ttl = _require_cache_ttl(ttl, action="lock")
+        provider = self._providers.require("cache")
+        lock_factory = getattr(provider, "lock", None)
+        if not callable(lock_factory):
+            raise PzError(
+                code="PZ_CACHE_LOCK_UNSUPPORTED",
+                message="Registered cache provider does not expose lock().",
+                stage="cache",
+                owner="infra.cache",
+                action="lock",
+            )
+        return lock_factory(key, ttl=ttl)

pz_core/runtime/facades/database.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from pz_core.runtime.errors import PzError
+from pz_core.infra.db import DatabaseAdapter
+from pz_core.runtime.facades._capabilities import merged_capability_status
+from pz_core.runtime.facades.providers import ProviderFacade
+from pz_core.runtime.plan import RuntimePlan
+from pz_core.runtime.registries import CapabilityStatus
+
+
+class DatabaseFacade:
+    def __init__(self, plan: RuntimePlan, providers: ProviderFacade) -> None:
+        if not isinstance(plan, RuntimePlan):
+            raise PzError(
+                code="PZ_DATABASE_PLAN_INVALID",
+                message="DatabaseFacade requires a RuntimePlan instance.",
+                stage="database",
+                owner="runtime.database",
+                action="bind_database_facade",
+            )
+        if not hasattr(providers, "require"):
+            raise PzError(
+                code="PZ_DATABASE_PROVIDERS_INVALID",
+                message="DatabaseFacade providers must expose require().",
+                stage="database",
+                owner="runtime.database",
+                action="bind_database_facade",
+            )
+        self._plan = plan
+        self._providers = providers
+
+    def status(self) -> CapabilityStatus:
+        return merged_capability_status(self._plan, self._providers, "database")
+
+    def connection(self) -> DatabaseAdapter:
+        provider = self._providers.require("database")
+        if not isinstance(provider, DatabaseAdapter):
+            raise PzError(
+                code="PZ_DATABASE_PROVIDER_INVALID",
+                message="Registered database provider does not implement DatabaseAdapter.",
+                stage="database",
+                owner="infra.database",
+                action="connection",
+            )
+        return provider
+
+    def session(self):
+        connection = self.connection()
+        factory = getattr(connection, "create_session", None)
+        if not callable(factory):
+            raise PzError(
+                code="PZ_DATABASE_SESSION_UNSUPPORTED",
+                message="Registered database adapter does not expose create_session().",
+                stage="database",
+                owner="infra.database",
+                action="session",
+            )
+        return factory()
+
+    def transaction(self):
+        session = self.session()
+        begin = getattr(session, "begin", None)
+        if not callable(begin):
+            raise PzError(
+                code="PZ_DATABASE_TRANSACTION_UNSUPPORTED",
+                message="Database session does not expose begin().",
+                stage="database",
+                owner="infra.database",
+                action="transaction",
+            )
+        return begin()