pz-cli 5.0.0__py3-none-any.whl

pz_core/infra/db/contracts.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class DatabaseTransaction(Protocol):
+    def commit(self) -> None: ...
+
+    def rollback(self) -> None: ...
+
+
+@runtime_checkable
+class DatabaseSession(Protocol):
+    def begin(self) -> DatabaseTransaction: ...
+
+    def execute(self, statement: str, *args: Any, **kwargs: Any) -> Any: ...
+
+
+@runtime_checkable
+class DatabaseReadinessProbe(Protocol):
+    def check_ready(self) -> bool: ...
+
+
+@runtime_checkable
+class DatabaseAdapter(Protocol):
+    def create_session(self) -> DatabaseSession: ...
+
+    def readiness_probe(self) -> DatabaseReadinessProbe: ...
+
+
+@dataclass(frozen=True, slots=True)
+class DbOwner:
+    app_id: str
+    module_path: str
+    owner: str
+
+
+@dataclass(frozen=True, slots=True)
+class MigrationSource:
+    app_id: str
+    owner: str
+    module_path: str
+    version: str
+    package_root: str
+    migrations_dir: str
+    models_module: str | None = None
+    files: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class DatabaseMigrationSnapshot:
+    workspace_dir: Path
+    manifest_path: Path
+    orm_config_path: Path
+    lock_path: Path
+    database_enabled: bool
+    database_driver: str
+    migration_executor: str | None
+    migration_owners: tuple[DbOwner, ...]
+    migration_sources: tuple[MigrationSource, ...]
+    history_entries: dict[str, tuple[str, ...]]
+
+
+@runtime_checkable
+class DatabaseMigrationPort(Protocol):
+    def status(self) -> DatabaseMigrationSnapshot: ...
+
+    def prepare(self, *, action: str) -> DatabaseMigrationSnapshot: ...
+
+    def execute(self, *, action: str) -> tuple[DatabaseMigrationSnapshot, dict[str, Any] | None]: ...

pz_core/infra/health/__init__.py

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

pz_core/infra/health/contracts.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class HealthProbe(Protocol):
+    def check_ready(self) -> bool: ...

pz_core/infra/kv/__init__.py

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

pz_core/infra/kv/contracts.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class CachePort(Protocol):
+    def get(self, key: str) -> Any: ...
+
+    def set(self, key: str, value: Any, *, ttl_seconds: int | None = None) -> None: ...
+
+    def delete(self, key: str) -> None: ...
+
+
+@runtime_checkable
+class CacheClientFactory(Protocol):
+    def create_cache(self) -> CachePort: ...

pz_core/infra/observability/__init__.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from .contracts import (
+    CounterPort,
+    HistogramPort,
+    LoggerPort,
+    NoopObservability,
+    NoopSpan,
+    ObservabilityPort,
+    ObservabilityStatus,
+    SpanPort,
+)
+
+__all__ = [
+    "CounterPort",
+    "HistogramPort",
+    "LoggerPort",
+    "NoopObservability",
+    "NoopSpan",
+    "ObservabilityPort",
+    "ObservabilityStatus",
+    "SpanPort",
+]

pz_core/infra/observability/contracts.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Literal, Protocol, runtime_checkable
+
+ObservabilityStatus = Literal["disabled", "enabled", "ready", "unavailable"]
+
+
+@runtime_checkable
+class LoggerPort(Protocol):
+    def debug(self, message: str, *args: object, **kwargs: object) -> None: ...
+    def info(self, message: str, *args: object, **kwargs: object) -> None: ...
+    def warning(self, message: str, *args: object, **kwargs: object) -> None: ...
+    def error(self, message: str, *args: object, **kwargs: object) -> None: ...
+
+
+@runtime_checkable
+class CounterPort(Protocol):
+    def add(
+        self,
+        value: int | float = 1,
+        *,
+        attributes: Mapping[str, object] | None = None,
+    ) -> None: ...
+
+
+@runtime_checkable
+class HistogramPort(Protocol):
+    def record(
+        self,
+        value: int | float,
+        *,
+        attributes: Mapping[str, object] | None = None,
+    ) -> None: ...
+
+
+@runtime_checkable
+class SpanPort(Protocol):
+    def __enter__(self) -> "SpanPort": ...
+    def __exit__(self, exc_type: object, exc: object, tb: object) -> bool | None: ...
+
+
+@runtime_checkable
+class ObservabilityPort(Protocol):
+    def status(self) -> ObservabilityStatus: ...
+    def logger(self, name: str) -> LoggerPort: ...
+    def counter(
+        self,
+        name: str,
+        *,
+        unit: str | None = None,
+        description: str | None = None,
+    ) -> CounterPort: ...
+    def histogram(
+        self,
+        name: str,
+        *,
+        unit: str | None = None,
+        description: str | None = None,
+    ) -> HistogramPort: ...
+    def span(
+        self,
+        name: str,
+        *,
+        attributes: Mapping[str, object] | None = None,
+    ) -> SpanPort: ...
+
+
+class _NoopLogger:
+    def debug(self, message: str, *args: object, **kwargs: object) -> None:
+        return None
+
+    def info(self, message: str, *args: object, **kwargs: object) -> None:
+        return None
+
+    def warning(self, message: str, *args: object, **kwargs: object) -> None:
+        return None
+
+    def error(self, message: str, *args: object, **kwargs: object) -> None:
+        return None
+
+
+class _NoopCounter:
+    def add(
+        self,
+        value: int | float = 1,
+        *,
+        attributes: Mapping[str, object] | None = None,
+    ) -> None:
+        return None
+
+
+class _NoopHistogram:
+    def record(
+        self,
+        value: int | float,
+        *,
+        attributes: Mapping[str, object] | None = None,
+    ) -> None:
+        return None
+
+
+class NoopSpan:
+    def __enter__(self) -> "NoopSpan":
+        return self
+
+    def __exit__(self, exc_type: object, exc: object, tb: object) -> bool | None:
+        return None
+
+
+class NoopObservability:
+    def status(self) -> ObservabilityStatus:
+        return "disabled"
+
+    def logger(self, name: str) -> LoggerPort:
+        return _NoopLogger()
+
+    def counter(
+        self,
+        name: str,
+        *,
+        unit: str | None = None,
+        description: str | None = None,
+    ) -> CounterPort:
+        return _NoopCounter()
+
+    def histogram(
+        self,
+        name: str,
+        *,
+        unit: str | None = None,
+        description: str | None = None,
+    ) -> HistogramPort:
+        return _NoopHistogram()
+
+    def span(
+        self,
+        name: str,
+        *,
+        attributes: Mapping[str, object] | None = None,
+    ) -> SpanPort:
+        return NoopSpan()

pz_core/infra/resilience/__init__.py

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

pz_core/infra/resilience/contracts.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
+
+
+@dataclass(frozen=True, slots=True)
+class RetryPolicy:
+    max_attempts: int = 1
+    base_delay_seconds: float = 0.0
+
+
+@runtime_checkable
+class FileLockPort(Protocol):
+    def acquire(self) -> bool: ...
+
+    def release(self) -> None: ...

pz_core/infra/resources/__init__.py

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

pz_core/infra/resources/contracts.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+
+@dataclass(frozen=True, slots=True)
+class ResourceBuildResult:
+    manifest_path: Path
+    output_dir: Path
+
+
+@runtime_checkable
+class ResourceBuildPort(Protocol):
+    def build(self, *, force: bool = False) -> ResourceBuildResult: ...

pz_core/infra/settings/__init__.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from .models import (
+    InfraContext,
+    InfraComponent,
+    ResourceItemContract,
+    ResilienceSettings,
+    ResourceSettings,
+)
+
+__all__ = [
+    "InfraContext",
+    "InfraComponent",
+    "ResourceItemContract",
+    "ResilienceSettings",
+    "ResourceSettings",
+]

pz_core/infra/settings/models.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class InfraComponent:
+    name: str
+    payload: Mapping[str, Any]
+
+    @property
+    def enabled(self) -> bool:
+        return bool(self.payload.get("enabled", False))
+
+    @property
+    def status(self) -> str:
+        raw = self.payload.get("status", self.payload.get("state"))
+        if isinstance(raw, str) and raw.strip():
+            return raw.strip()
+        return "enabled" if self.enabled else "disabled"
+
+    @property
+    def reason(self) -> str | None:
+        raw = self.payload.get("reason")
+        if raw is None:
+            return None
+        value = str(raw).strip()
+        return value or None
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self.payload.get(key, default)
+
+
+@dataclass(frozen=True, slots=True)
+class ResilienceSettings:
+    lock_dir: Path
+
+
+@dataclass(frozen=True, slots=True)
+class ResourceItemContract:
+    name: str
+    output_dir: Path
+
+
+@dataclass(frozen=True, slots=True)
+class ResourceSettings:
+    items: tuple[ResourceItemContract, ...]
+    output_dir: Path
+    lock_path: Path
+    manifest_path: Path
+    staging_dir: Path
+    manifest_name: str
+    lock_name: str
+
+
+@dataclass(frozen=True, slots=True)
+class InfraContext:
+    project_dir: Path
+    cache_dir: Path
+    runtime_dir: Path
+    asset_dir: Path
+    database: InfraComponent
+    cache: InfraComponent
+    metrics: InfraComponent
+    tracing: InfraComponent
+    mail: InfraComponent
+    storage: InfraComponent
+    health: InfraComponent
+    resilience: ResilienceSettings
+    resources: ResourceSettings
+
+    @property
+    def enabled_components(self) -> tuple[str, ...]:
+        out: list[str] = []
+        for name in ("database", "cache", "metrics", "tracing", "mail", "storage", "health"):
+            if getattr(self, name).enabled:
+                out.append(name)
+        return tuple(out)

pz_core/infra/storage/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from .ports import PresignInfo, StoragePort, StoredObject
+
+__all__ = ["PresignInfo", "StoragePort", "StoredObject"]

pz_core/infra/storage/ports.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
+
+
+@dataclass(frozen=True, slots=True)
+class StoredObject:
+    object_key: str
+    size: int | None = None
+    content_type: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class PresignInfo:
+    method: str
+    url: str
+    expires_in_seconds: int
+
+
+@runtime_checkable
+class StoragePort(Protocol):
+    def store_bytes(self, object_key: str, payload: bytes, *, content_type: str | None = None) -> StoredObject: ...
+
+    def delete(self, object_key: str) -> None: ...
+
+    def presign_get(self, object_key: str, *, expires_in_seconds: int) -> PresignInfo: ...