pz-cli 5.0.0__py3-none-any.whl

pz_settings_center/public.py

@@ -0,0 +1,139 @@
+"""Formal contrib-level public surface for unified settings access."""
+
+from __future__ import annotations
+
+from typing import Any
+from dataclasses import dataclass
+
+import pz_core.runtime.settings as _runtime
+
+from .api import runtime_overrides
+from .integration_payload import IntegrationPayloadSettings, empty_integration_payload
+from .project_helpers import get_project_dir, get_project_upload_path
+from .typed_settings import SettingsCenterProxy, resolve_app_settings_payload, resolve_settings, settings
+from .routing_helpers import get_routing_default_language, get_routing_language_aliases, get_routing_supported_languages
+
+
+ResolvedSettings = _runtime.ResolvedSettings
+
+active_settings_project = _runtime.active_settings_project
+bind_settings_snapshot = _runtime.bind_settings_snapshot
+bound_settings_snapshot = _runtime.bound_settings_snapshot
+build_local_default_settings = _runtime.build_local_default_settings
+build_local_default_settings_chain = _runtime.build_local_default_settings_chain
+current_pz_env = _runtime.current_pz_env
+current_settings_project_dir = _runtime.current_settings_project_dir
+ensure_full_settings = _runtime.ensure_full_settings
+get_route_token_catalog = _runtime.get_route_token_catalog
+get_applied_runtime_overrides = runtime_overrides.get_applied_runtime_overrides
+load_local_default_settings = _runtime.load_local_default_settings
+load_local_default_settings_chain = _runtime.load_local_default_settings_chain
+register_route_token_catalog_provider = _runtime.register_route_token_catalog_provider
+reset_route_token_catalog_provider = _runtime.reset_route_token_catalog_provider
+reset_settings_binding = _runtime.reset_settings_binding
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeNamespaceSettingsSnapshot:
+    namespace: str
+    values: dict[str, Any]
+    signature: tuple[Any, ...]
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self.values.get(str(key), default)
+
+
+_RUNTIME_NAMESPACE_SETTINGS_CACHE: dict[
+    tuple[str, str | None, int, tuple[Any, ...]],
+    RuntimeNamespaceSettingsSnapshot,
+] = {}
+
+
+def get_settings_snapshot(*, project_dir: str | None = None):
+    return resolve_settings(project_dir=project_dir).snapshot
+
+
+def get_settings_snapshot_section(
+    name: str,
+    *,
+    project_dir: str | None = None,
+    default: Any = None,
+):
+    snapshot = get_settings_snapshot(project_dir=project_dir)
+    getter = getattr(snapshot, "get", None)
+    if callable(getter):
+        value = getter(str(name).strip(), default=default)
+    else:
+        value = getattr(snapshot, str(name).strip(), default)
+    return default if value is None else value
+
+
+def _signature_value(value: Any) -> Any:
+    if isinstance(value, dict):
+        return tuple((str(key), _signature_value(item)) for key, item in sorted(value.items(), key=lambda item: str(item[0])))
+    if isinstance(value, (list, tuple)):
+        return tuple(_signature_value(item) for item in value)
+    if isinstance(value, set):
+        return tuple(sorted(_signature_value(item) for item in value))
+    return value
+
+
+def get_runtime_namespace_settings_snapshot(
+    namespace: str,
+    *,
+    project_dir: str | None = None,
+) -> RuntimeNamespaceSettingsSnapshot:
+    app_id = str(namespace or "").strip()
+    if not app_id:
+        raise ValueError("namespace must be a non-empty app_id string")
+    resolved = resolve_settings(project_dir=project_dir)
+    resolved_project_dir = getattr(resolved, "project_dir", project_dir)
+    runtime_signature = runtime_overrides.get_runtime_overrides_signature(project_dir=project_dir)
+    cache_key = (app_id, str(resolved_project_dir) if resolved_project_dir is not None else None, id(getattr(resolved, "snapshot", None)), runtime_signature)
+    cached = _RUNTIME_NAMESPACE_SETTINGS_CACHE.get(cache_key)
+    if cached is not None:
+        return cached
+    values = dict(resolve_app_settings_payload(resolved, app_id) or {})
+    signature = (
+        app_id,
+        id(getattr(resolved, "snapshot", None)),
+        runtime_signature,
+        _signature_value(values),
+    )
+    snapshot = RuntimeNamespaceSettingsSnapshot(namespace=app_id, values=values, signature=signature)
+    _RUNTIME_NAMESPACE_SETTINGS_CACHE[cache_key] = snapshot
+    return snapshot
+
+
+__all__ = [
+    "ResolvedSettings",
+    "RuntimeNamespaceSettingsSnapshot",
+    "SettingsCenterProxy",
+    "IntegrationPayloadSettings",
+    "active_settings_project",
+    "bind_settings_snapshot",
+    "bound_settings_snapshot",
+    "build_local_default_settings",
+    "build_local_default_settings_chain",
+    "current_pz_env",
+    "current_settings_project_dir",
+    "ensure_full_settings",
+    "empty_integration_payload",
+    "get_applied_runtime_overrides",
+    "get_route_token_catalog",
+    "get_project_dir",
+    "get_project_upload_path",
+    "get_routing_default_language",
+    "get_routing_language_aliases",
+    "get_routing_supported_languages",
+    "get_runtime_namespace_settings_snapshot",
+    "get_settings_snapshot",
+    "get_settings_snapshot_section",
+    "load_local_default_settings",
+    "load_local_default_settings_chain",
+    "register_route_token_catalog_provider",
+    "reset_route_token_catalog_provider",
+    "reset_settings_binding",
+    "resolve_settings",
+    "settings",
+]

pz_settings_center/routing_helpers.py

@@ -0,0 +1,73 @@
+"""Routing-level helper accessors built on the formal ``routing`` snapshot section."""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any
+
+
+def _settings_snapshot(project_dir: str | None = None):
+    getter = import_module("pz_settings_center.public").get_settings_snapshot
+    return getter(project_dir=project_dir)
+
+
+def _routing_value(name: str, default: Any = None, *, project_dir: str | None = None) -> Any:
+    snapshot = _settings_snapshot(project_dir=project_dir)
+    getter = getattr(snapshot, "get", None)
+    if not callable(getter):
+        return default
+    key = str(name or "").strip()
+    if not key:
+        return default
+    value = getter("routing", key, default=None)
+    return default if value is None else value
+
+
+def get_routing_default_language(default: str = "en", *, project_dir: str | None = None) -> str:
+    try:
+        value = str(_routing_value("default_language", default, project_dir=project_dir) or default).strip()
+    except Exception:
+        value = default
+    return value or default
+
+
+def get_routing_supported_languages(
+    default: tuple[str, ...] = ("en",),
+    *,
+    project_dir: str | None = None,
+) -> tuple[str, ...]:
+    try:
+        values = _routing_value("all_supported_languages", (), project_dir=project_dir) or ()
+    except Exception:
+        values = ()
+    if not isinstance(values, (list, tuple, set)):
+        return tuple(default)
+    languages = tuple(str(item).strip() for item in values if str(item).strip())
+    return languages or tuple(default)
+
+
+def get_routing_language_aliases(
+    default: dict[str, str] | None = None,
+    *,
+    project_dir: str | None = None,
+) -> dict[str, str]:
+    try:
+        values = _routing_value("language_aliases", {}, project_dir=project_dir) or {}
+    except Exception:
+        values = {}
+    if not isinstance(values, dict):
+        return dict(default or {})
+    aliases: dict[str, str] = {}
+    for raw_alias, raw_target in values.items():
+        alias = str(raw_alias or "").strip().strip("/")
+        target = str(raw_target or "").strip().strip("/")
+        if alias and target:
+            aliases[alias] = target
+    return aliases or dict(default or {})
+
+
+__all__ = [
+    "get_routing_default_language",
+    "get_routing_language_aliases",
+    "get_routing_supported_languages",
+]

pz_settings_center/runtime_override_provider.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pz_core.core.extensions import SettingsPatch, SettingsProviderContext
+
+from .api import runtime_overrides
+
+
+def build_runtime_override_settings_provider(
+    context: SettingsProviderContext,
+) -> tuple[SettingsPatch, ...]:
+    project_dir = getattr(getattr(context, "project", None), "project_dir", None)
+    snapshot = getattr(context, "snapshot", None)
+    allowed_namespaces = {
+        str(app_id).strip()
+        for app_id in dict(getattr(snapshot, "apps", {}) or {}).keys()
+        if str(app_id).strip()
+    }
+    schema_by_namespace = runtime_overrides.get_runtime_overrides_schema()
+    patches: list[SettingsPatch] = []
+    for namespace, raw_values in runtime_overrides.get_applied_runtime_overrides(project_dir).items():
+        source = str(namespace or "").strip()
+        if source not in allowed_namespaces:
+            continue
+        schema = dict(schema_by_namespace.get(source, {}) or {})
+        if not schema:
+            continue
+        payload: dict[str, Any] = {}
+        for key, value in dict(raw_values or {}).items():
+            field_name = str(key or "").strip()
+            if field_name in schema:
+                payload[field_name] = value
+        if payload:
+            patches.append(
+                SettingsPatch(
+                    app_id=source,
+                    payload=payload,
+                    source="pz_settings_center.runtime_overrides",
+                    priority=10000,
+                )
+            )
+    return tuple(patches)
+
+
+class RuntimeOverrideSettingsProvider:
+    def provide(
+        self,
+        context: SettingsProviderContext,
+    ) -> tuple[SettingsPatch, ...]:
+        return build_runtime_override_settings_provider(context)
+
+
+SETTINGS_PROVIDER = RuntimeOverrideSettingsProvider()
+
+
+__all__ = [
+    "RuntimeOverrideSettingsProvider",
+    "SETTINGS_PROVIDER",
+    "build_runtime_override_settings_provider",
+]

pz_settings_center/typed_settings.py

@@ -0,0 +1,324 @@
+"""Application-facing typed settings loading for settings_center."""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from importlib import import_module
+from types import ModuleType
+from typing import Any, Mapping
+
+ResolvedSettings = Any
+_APP_SETTINGS_TYPE_CACHE: dict[tuple[int, str | None, str], type | None] = {}
+
+
+def resolve_settings(project_dir: str | None = None) -> ResolvedSettings:
+    runtime_module = import_module("pz_core.runtime")
+    return runtime_module.resolve_settings(project_dir=project_dir)
+
+
+def _active_resolve_settings(project_dir: str | None = None):
+    """Resolve settings lazily through the public surface.
+
+    Importing settings_center must stay side-effect free. The first concrete
+    read from SettingsCenterProxy is the point where the active SettingsSnapshot
+    may be compiled or an already-bound runtime snapshot is reused.
+    """
+    resolver = import_module("pz_settings_center.public").resolve_settings
+    return resolver(project_dir=project_dir)
+
+
+def _normalize_key_token(value: Any) -> str:
+    return str(value or "").strip().replace("-", "_").lower()
+
+
+def _iter_validation_aliases(field_info: Any) -> tuple[str, ...]:
+    alias = getattr(field_info, "validation_alias", None)
+    if alias is None:
+        return ()
+    if isinstance(alias, str):
+        return (alias,)
+    choices = getattr(alias, "choices", None)
+    if choices is not None:
+        values: list[str] = []
+        for item in tuple(choices or ()):
+            if isinstance(item, str):
+                values.append(item)
+                continue
+            path = getattr(item, "path", None)
+            if isinstance(path, tuple) and len(path) == 1 and isinstance(path[0], str):
+                values.append(path[0])
+        return tuple(values)
+    path = getattr(alias, "path", None)
+    if isinstance(path, tuple) and len(path) == 1 and isinstance(path[0], str):
+        return (path[0],)
+    return ()
+
+
+@lru_cache(maxsize=None)
+def _field_name_lookup(settings_type: type) -> dict[str, str]:
+    model_fields = getattr(settings_type, "model_fields", None)
+    if not isinstance(model_fields, Mapping):
+        return {}
+    lookup: dict[str, str] = {}
+    for field_name, field_info in model_fields.items():
+        candidates = {
+            str(field_name).strip(),
+            str(getattr(field_info, "alias", "") or "").strip(),
+            *_iter_validation_aliases(field_info),
+        }
+        for candidate in candidates:
+            token = _normalize_key_token(candidate)
+            if token and token not in lookup:
+                lookup[token] = str(field_name)
+    return lookup
+
+
+def _normalize_settings_payload_keys(payload: Mapping[str, Any] | None, settings_type: type) -> dict[str, Any]:
+    lookup = _field_name_lookup(settings_type)
+    if not lookup:
+        return dict(payload or {})
+    normalized: dict[str, Any] = {}
+    for raw_key, value in dict(payload or {}).items():
+        key = str(raw_key or "").strip()
+        if not key:
+            continue
+        normalized[lookup.get(_normalize_key_token(key), key)] = value
+    return normalized
+
+
+def _is_missing_module_error(exc: ModuleNotFoundError, module_name: str) -> bool:
+    missing_name = str(getattr(exc, "name", "") or "")
+    return missing_name == module_name or module_name.startswith(missing_name + ".")
+
+
+def _import_optional_module(module_name: str) -> ModuleType | None:
+    try:
+        return import_module(module_name)
+    except ModuleNotFoundError as exc:
+        if _is_missing_module_error(exc, module_name):
+            return None
+        raise
+
+
+def _snapshot_installed_app_paths(resolved: Any) -> tuple[str, ...]:
+    snapshot = getattr(resolved, "snapshot", None)
+    values: list[str] = []
+    for attr_name in ("installed_apps", "declared_installed_apps"):
+        for item in tuple(getattr(snapshot, attr_name, ()) or ()):
+            text = str(item or "").strip()
+            if text and text not in values:
+                values.append(text)
+    return tuple(values)
+
+
+def _declared_app_ids(resolved: Any) -> frozenset[str]:
+    snapshot = getattr(resolved, "snapshot", None)
+    apps = getattr(snapshot, "apps", None)
+    if isinstance(apps, Mapping):
+        return frozenset(str(app_id) for app_id in apps.keys())
+    return frozenset()
+
+
+def _candidate_settings_module_names(resolved: Any, app_id: str) -> tuple[str, ...]:
+    normalized_app_id = str(app_id or "").strip().replace("-", "_")
+    names: list[str] = []
+    if normalized_app_id:
+        names.append(f"{normalized_app_id}.settings")
+    resolver = import_module("pz_core.assembly.app_discovery").resolve_declared_app_id
+    for module_path in _snapshot_installed_app_paths(resolved):
+        try:
+            declared_app_id = str(resolver(module_path) or "").strip()
+        except Exception:
+            declared_app_id = ""
+        if declared_app_id != str(app_id or "").strip():
+            continue
+        normalized_module = module_path.replace("-", "_")
+        candidate = f"{normalized_module}.settings"
+        if candidate not in names:
+            names.append(candidate)
+    return tuple(names)
+
+
+def _project_import_context(resolved: Any):
+    snapshot = getattr(resolved, "snapshot", None)
+    project_dir = getattr(resolved, "project_dir", None) or getattr(snapshot, "project_dir", None)
+    import_roots = tuple(getattr(snapshot, "import_roots", ()) or ())
+    helper = import_module("pz_core.assembly.project").active_project_import_root
+    return helper(project_dir, extra_import_roots=import_roots)
+
+
+def _app_settings_module_and_type(resolved: Any, app_id: str) -> tuple[ModuleType, type] | tuple[None, None]:
+    normalized_app_id = str(app_id or "").strip()
+    if not normalized_app_id:
+        return None, None
+    snapshot = getattr(resolved, "snapshot", None)
+    project_dir = str(getattr(resolved, "project_dir", None) or getattr(snapshot, "project_dir", None) or "")
+    cache_key = (id(snapshot), project_dir or None, normalized_app_id)
+    if cache_key in _APP_SETTINGS_TYPE_CACHE:
+        settings_type = _APP_SETTINGS_TYPE_CACHE[cache_key]
+        if settings_type is None:
+            return None, None
+        module_name = str(getattr(settings_type, "__module__", "") or "").strip()
+        if not module_name:
+            return None, None
+        return import_module(module_name), settings_type
+    with _project_import_context(resolved):
+        for module_name in _candidate_settings_module_names(resolved, normalized_app_id):
+            module = _import_optional_module(module_name)
+            if module is None:
+                continue
+            declared_app_id = str(getattr(module, "APP_ID", "") or "").strip()
+            if declared_app_id and declared_app_id != normalized_app_id:
+                continue
+            settings_type = getattr(module, "AppSettings", None)
+            if isinstance(settings_type, type):
+                _APP_SETTINGS_TYPE_CACHE[cache_key] = settings_type
+                return module, settings_type
+    _APP_SETTINGS_TYPE_CACHE[cache_key] = None
+    return None, None
+
+
+def _normalize_with_app_schema(module: ModuleType, settings_type: type, values: dict[str, Any]) -> dict[str, Any]:
+    normalized = _normalize_settings_payload_keys(values, settings_type)
+    app_normalize = getattr(module, "_normalize_settings_payload", None)
+    if callable(app_normalize):
+        normalized = dict(app_normalize(normalized) or {})
+    return normalized
+
+
+def _typed_or_raw_app_namespace(resolved: Any, app_id: str) -> Any:
+    typed_app_settings = getattr(resolved, "typed_app_settings", None)
+    if not callable(typed_app_settings):
+        return getattr(resolved, app_id)
+    settings_module, settings_type = _app_settings_module_and_type(resolved, app_id)
+    if settings_type is None:
+        return getattr(resolved, app_id)
+    return typed_app_settings(
+        app_id,
+        settings_type,
+        normalize=lambda values: _normalize_with_app_schema(settings_module, settings_type, values),
+    )
+
+
+def _payload_from_namespace(namespace: Any) -> dict[str, Any]:
+    if isinstance(namespace, dict):
+        return dict(namespace)
+    model_dump = getattr(namespace, "model_dump", None)
+    if callable(model_dump):
+        mapped = model_dump()
+        if isinstance(mapped, dict):
+            return dict(mapped)
+    to_dict = getattr(namespace, "to_dict", None)
+    if callable(to_dict):
+        mapped = to_dict()
+        if isinstance(mapped, dict):
+            return dict(mapped)
+    return dict(getattr(namespace, "__dict__", {}) or {})
+
+
+def resolve_app_settings_payload(resolved: Any, app_id: str) -> dict[str, Any]:
+    return _payload_from_namespace(_typed_or_raw_app_namespace(resolved, app_id))
+
+
+def _mapping_path_value(mapping: dict[str, Any], path: tuple[str, ...], *, default: Any = None) -> Any:
+    current: Any = mapping
+    for key in path:
+        if not isinstance(current, dict) or key not in current:
+            return default
+        current = current[key]
+    return default if current is None else current
+
+
+class _NamespaceProxy:
+    def __init__(self, payload: Any) -> None:
+        self._payload = payload
+
+    def _mapping(self) -> dict[str, Any]:
+        if isinstance(self._payload, dict):
+            return self._payload
+        model_dump = getattr(self._payload, "model_dump", None)
+        if callable(model_dump):
+            mapped = model_dump()
+            if isinstance(mapped, dict):
+                return mapped
+        to_dict = getattr(self._payload, "to_dict", None)
+        if callable(to_dict):
+            mapped = to_dict()
+            if isinstance(mapped, dict):
+                return mapped
+        return getattr(self._payload, "__dict__", {})
+
+    def get(self, key: str, default: Any = None) -> Any:
+        mapping = self._mapping()
+        if key in mapping:
+            return _wrap_namespace(mapping[key])
+        return default
+
+    def to_dict(self) -> dict[str, Any]:
+        return dict(self._mapping())
+
+    def __getattr__(self, name: str) -> Any:
+        mapping = self._mapping()
+        if name not in mapping:
+            raise AttributeError(name)
+        return _wrap_namespace(mapping[name])
+
+    def __bool__(self) -> bool:
+        return bool(self._payload)
+
+    def __iter__(self):
+        return iter(self._mapping())
+
+    def items(self):
+        return self._mapping().items()
+
+
+def _wrap_namespace(payload: Any) -> Any:
+    if isinstance(payload, dict):
+        return _NamespaceProxy(payload)
+    if hasattr(payload, "to_dict"):
+        try:
+            mapped = payload.to_dict()
+        except Exception:
+            mapped = None
+        if isinstance(mapped, dict):
+            return _NamespaceProxy(mapped)
+    if hasattr(payload, "__dict__"):
+        mapping = getattr(payload, "__dict__", {}) or {}
+        if mapping:
+            return _NamespaceProxy(payload)
+    return payload
+
+
+class SettingsCenterProxy:
+    """Application-facing settings proxy with settings-only lazy autoload."""
+
+    @property
+    def project(self):
+        return _wrap_namespace(_active_resolve_settings().project)
+
+    def app_settings(self, app_id: str) -> dict[str, Any]:
+        return resolve_app_settings_payload(_active_resolve_settings(), app_id)
+
+    def get(self, *path: str, default: Any = None) -> Any:
+        resolved = _active_resolve_settings()
+        if path and str(path[0]).strip() in _declared_app_ids(resolved):
+            app_values = resolve_app_settings_payload(resolved, str(path[0]).strip())
+            if len(path) == 1:
+                return app_values
+            return _mapping_path_value(app_values, tuple(str(item) for item in path[1:]), default=default)
+        return resolved.get(*path, default=default)
+
+    def __getattr__(self, name: str) -> Any:
+        return _wrap_namespace(_typed_or_raw_app_namespace(_active_resolve_settings(), name))
+
+
+settings = SettingsCenterProxy()
+
+__all__ = [
+    "ResolvedSettings",
+    "SettingsCenterProxy",
+    "resolve_app_settings_payload",
+    "resolve_settings",
+    "settings",
+]

pz_settings_center/urls.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+
+app_name = "pz_settings_center"
+
+urlpatterns = ()
+
+
+__all__ = ["app_name", "urlpatterns"]