pz-cli 5.0.0__py3-none-any.whl

pz_foundation/apps.py

@@ -0,0 +1,127 @@
+"""Foundation app metadata."""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any
+
+from pz_core.core.extensions import (
+    ExtensionSpec,
+    HostBuilderSpec,
+    InfraProviderSpec,
+    LifecycleContributionSpec,
+    RuntimeManifestContributionSpec,
+)
+from pz_foundation.lazy_imports import LazyImportProxy
+
+def _foundation_lifecycle_module():
+    from . import lifecycle as foundation_lifecycle
+
+    return foundation_lifecycle
+
+
+def _foundation_web_builder():
+    module = import_module("pz_foundation.host.builder")
+    builder_cls = getattr(module, "FoundationWebHostBuilder")
+    return builder_cls()
+
+
+def _foundation_infra_provider():
+    module = import_module("pz_foundation.infra_provider")
+    return getattr(module, "INFRA_PROVIDER")
+
+
+def _foundation_url_manifest_provider():
+    module = import_module("pz_foundation.routing.manifest_provider")
+    provider_cls = getattr(module, "FoundationUrlManifestProvider")
+    return provider_cls()
+
+
+class FoundationApp:
+    id = "pz_foundation"
+    name = "Foundation"
+    version = "5.0.0"
+    required_pz = ">=5.0.0"
+
+    def middlewares(self, settings_snapshot: Any | None = None):
+        del settings_snapshot
+        return list(_foundation_lifecycle_module().MIDDLEWARES)
+
+    def extensions(self):
+        return [
+            HostBuilderSpec(
+                id="pz_foundation.host.builder.web",
+                owner_app=self.id,
+                title="Foundation Web Host Builder",
+                priority=100,
+                builder=LazyImportProxy(
+                    resolver=_foundation_web_builder,
+                    label="pz_foundation.host.builder.FoundationWebHostBuilder()",
+                    module_name="pz_foundation.host.builder",
+                    attr_name="FoundationWebHostBuilder",
+                    call_factory=True,
+                ),
+            ),
+            InfraProviderSpec(
+                id="pz_foundation.infra.provider",
+                owner_app=self.id,
+                title="Foundation Infra Provider",
+                priority=100,
+                provider=LazyImportProxy(
+                    resolver=_foundation_infra_provider,
+                    label="pz_foundation.infra_provider.INFRA_PROVIDER",
+                    module_name="pz_foundation.infra_provider",
+                    attr_name="INFRA_PROVIDER",
+                ),
+            ),
+            RuntimeManifestContributionSpec(
+                id="pz_foundation.url_manifest.provider",
+                owner_app=self.id,
+                title="Foundation URL Manifest Provider",
+                priority=100,
+                provider=LazyImportProxy(
+                    resolver=_foundation_url_manifest_provider,
+                    label="pz_foundation.routing.manifest_provider.FoundationUrlManifestProvider()",
+                    module_name="pz_foundation.routing.manifest_provider",
+                    attr_name="FoundationUrlManifestProvider",
+                    call_factory=True,
+                ),
+            ),
+            ExtensionSpec(
+                id="pz_foundation.resources.post_build.images",
+                owner_app=self.id,
+                kind="resources.post_build",
+                title="Foundation image derivative builder",
+                priority=40,
+                payload={
+                    "handler": "pz_foundation.resources.images:build_image_derivatives_into_resource_static",
+                },
+                source="contrib",
+            ),
+            LifecycleContributionSpec(
+                id="pz_foundation.lifecycle.startup",
+                owner_app=self.id,
+                phase="startup",
+                handler=self.startup,
+            ),
+            LifecycleContributionSpec(
+                id="pz_foundation.lifecycle.shutdown",
+                owner_app=self.id,
+                phase="shutdown",
+                handler=self.shutdown,
+            ),
+        ]
+
+    def providers(self):
+        return _foundation_lifecycle_module().PROVIDERS
+
+    def startup(self, host, context) -> None:  # noqa: ANN001
+        return _foundation_lifecycle_module().startup_foundation(host, context, app_id=self.id)
+
+    def shutdown(self, host, context) -> None:  # noqa: ANN001
+        return _foundation_lifecycle_module().shutdown_foundation(host, context, app_id=self.id)
+
+
+app = FoundationApp()
+
+__all__ = ["FoundationApp", "app"]

pz_foundation/auth/__init__.py

@@ -0,0 +1 @@
+"""Reserved package for advanced auth registration logic."""

pz_foundation/cache_control.py

@@ -0,0 +1,233 @@
+"""Unified cache control policy registry."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Mapping
+
+import pz_settings_center.public as settings_center
+
+
+@dataclass(frozen=True, slots=True)
+class CacheControlPolicy:
+    id: str
+    enabled: bool = False
+    ttl_seconds: float = 0.0
+    max_entries: int | None = None
+    shared_invalidation_versions: bool | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class CacheControlRule:
+    prefix: str
+    value: str
+
+
+@dataclass(frozen=True, slots=True)
+class CacheControlHttpFileExtensions:
+    js_css: tuple[str, ...] = ()
+    images: tuple[str, ...] = ()
+    fonts: tuple[str, ...] = ()
+    static_data: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class CacheControlHttpSettings:
+    rules: tuple[CacheControlRule, ...] = ()
+    no_store_path_prefixes: tuple[str, ...] = ()
+    no_store_path_tokens: tuple[str, ...] = ()
+    versioned_asset_query_keys: tuple[str, ...] = ()
+    file_extensions: CacheControlHttpFileExtensions = field(default_factory=CacheControlHttpFileExtensions)
+
+
+def _as_mapping(value: Any) -> dict[str, Any]:
+    if value is None:
+        return {}
+    if isinstance(value, Mapping):
+        return dict(value)
+    if hasattr(value, "model_dump"):
+        try:
+            payload = value.model_dump()
+            return dict(payload) if isinstance(payload, Mapping) else {}
+        except Exception:
+            return {}
+    if hasattr(value, "to_dict"):
+        try:
+            payload = value.to_dict()
+            return dict(payload) if isinstance(payload, Mapping) else {}
+        except Exception:
+            return {}
+    if hasattr(value, "__dict__"):
+        try:
+            payload = dict(vars(value))
+            inner = payload.get("_payload")
+            if isinstance(inner, Mapping):
+                return dict(inner)
+            return payload
+        except Exception:
+            return {}
+    return {}
+
+
+def _bool_value(value: Any, default: bool = True) -> bool:
+    if isinstance(value, bool):
+        return value
+    if value is None:
+        return default
+    if isinstance(value, (int, float)):
+        return bool(value)
+    text = str(value).strip().lower()
+    if text in {"1", "true", "yes", "on"}:
+        return True
+    if text in {"0", "false", "no", "off"}:
+        return False
+    return default
+
+
+def _float_value(value: Any, default: float = 0.0) -> float:
+    try:
+        return float(value)
+    except Exception:
+        return float(default)
+
+
+def _int_or_none(value: Any) -> int | None:
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except Exception:
+        return None
+
+
+def _current_pz_env() -> str:
+    return str(settings_center.current_pz_env(default="develop") or "develop").strip().lower() or "develop"
+
+
+def _string_sequence(value: Any, *, lowercase: bool = False) -> tuple[str, ...]:
+    if value is None:
+        return ()
+    if isinstance(value, str):
+        items = tuple(part.strip() for part in value.split(",") if part.strip())
+    elif isinstance(value, (list, tuple, set)):
+        items = tuple(str(part).strip() for part in value if str(part).strip())
+    else:
+        return ()
+    if lowercase:
+        return tuple(item.lower() for item in items)
+    return items
+
+
+def _configured_cache_control_map() -> dict[str, Any]:
+    try:
+        foundation_settings = getattr(settings_center.settings, "pz_foundation")
+        cache_control = getattr(foundation_settings, "cache_control", None)
+    except Exception:
+        cache_control = None
+    return _as_mapping(cache_control)
+
+
+def _runtime_enabled_payload(cache_control: Mapping[str, Any]) -> dict[str, Any]:
+    return _as_mapping(cache_control.get("runtime_enabled"))
+
+
+def _global_cache_control_enabled() -> bool:
+    runtime_enabled = _runtime_enabled_payload(_configured_cache_control_map())
+    if runtime_enabled.get("enabled") is not None:
+        return _bool_value(runtime_enabled.get("enabled"), True)
+    pz_env = _current_pz_env()
+    by_env = _as_mapping(runtime_enabled.get("by_pz_env"))
+    if pz_env in by_env:
+        return _bool_value(by_env.get(pz_env), True)
+    if "default" in runtime_enabled:
+        return _bool_value(runtime_enabled.get("default"), True)
+    return False
+
+
+def _configured_policy_map() -> dict[str, Any]:
+    payload = _configured_cache_control_map()
+    policies = payload.get("policies")
+    return _as_mapping(policies)
+
+
+def resolve_cache_control_http_settings() -> CacheControlHttpSettings:
+    payload = _configured_cache_control_map()
+    http = _as_mapping(payload.get("http"))
+    extensions = _as_mapping(http.get("file_extensions"))
+    rules_payload = http.get("rules")
+    rules: list[CacheControlRule] = []
+    if isinstance(rules_payload, (list, tuple)):
+        for item in rules_payload:
+            rule = _as_mapping(item)
+            prefix = str(rule.get("prefix") or "").strip().lower()
+            value = str(rule.get("value") or "").strip()
+            if prefix and value:
+                rules.append(CacheControlRule(prefix=prefix, value=value))
+    return CacheControlHttpSettings(
+        rules=tuple(rules),
+        no_store_path_prefixes=_string_sequence(http.get("no_store_path_prefixes"), lowercase=True),
+        no_store_path_tokens=_string_sequence(http.get("no_store_path_tokens"), lowercase=True),
+        versioned_asset_query_keys=_string_sequence(http.get("versioned_asset_query_keys"), lowercase=True),
+        file_extensions=CacheControlHttpFileExtensions(
+            js_css=_string_sequence(extensions.get("js_css"), lowercase=True),
+            images=_string_sequence(extensions.get("images"), lowercase=True),
+            fonts=_string_sequence(extensions.get("fonts"), lowercase=True),
+            static_data=_string_sequence(extensions.get("static_data"), lowercase=True),
+        ),
+    )
+
+
+def resolve_cache_control_policy(policy_id: str) -> CacheControlPolicy:
+    normalized_id = str(policy_id or "").strip()
+    configured = _as_mapping(_configured_policy_map().get(normalized_id))
+    global_enabled = _global_cache_control_enabled()
+    return CacheControlPolicy(
+        id=normalized_id,
+        enabled=global_enabled and _bool_value(configured.get("enabled"), False),
+        ttl_seconds=max(0.0, _float_value(configured.get("ttl_seconds"), 0.0)),
+        max_entries=_int_or_none(configured.get("max_entries")),
+        shared_invalidation_versions=(
+            None
+            if configured.get("shared_invalidation_versions") is None
+            else _bool_value(configured.get("shared_invalidation_versions"), True)
+        ),
+    )
+
+
+def cache_policy_enabled(policy_id: str) -> bool:
+    return resolve_cache_control_policy(policy_id).enabled
+
+
+def cache_policy_ttl_seconds(policy_id: str) -> float:
+    policy = resolve_cache_control_policy(policy_id)
+    return policy.ttl_seconds if policy.enabled else 0.0
+
+
+def cache_policy_max_entries(policy_id: str) -> int:
+    policy = resolve_cache_control_policy(policy_id)
+    if not policy.enabled:
+        return 0
+    return max(0, int(policy.max_entries if policy.max_entries is not None else 0))
+
+
+def cache_policy_shared_invalidation_versions(policy_id: str) -> bool:
+    policy = resolve_cache_control_policy(policy_id)
+    if not policy.enabled:
+        return False
+    if policy.shared_invalidation_versions is None:
+        return False
+    return bool(policy.shared_invalidation_versions)
+
+
+__all__ = [
+    "CacheControlHttpFileExtensions",
+    "CacheControlHttpSettings",
+    "CacheControlPolicy",
+    "CacheControlRule",
+    "cache_policy_enabled",
+    "cache_policy_max_entries",
+    "cache_policy_shared_invalidation_versions",
+    "cache_policy_ttl_seconds",
+    "resolve_cache_control_http_settings",
+    "resolve_cache_control_policy",
+]

pz_foundation/cli/__init__.py

@@ -0,0 +1,2 @@
+"""Foundation app CLI tools."""
+