pz-cli 5.0.0__py3-none-any.whl

pz_core/assembly/middlewares/compiler.py

@@ -0,0 +1,508 @@
+from __future__ import annotations
+
+from dataclasses import asdict, is_dataclass
+import inspect
+from typing import Mapping
+from typing import Any
+
+from pz_core.assembly.app_discovery import read_static_app_declaration
+from pz_core.assembly.apps import AppRegistry, load_app_entrypoint_object_from_decl
+from pz_core.assembly.project import active_project_import_root
+from pz_core.assembly.settings import SettingsSnapshot
+from pz_core.core.errors import PzError
+from pz_core.core.middlewares import MiddlewareDecl, MiddlewareManifest
+
+
+def _read_required_string(
+    value: object,
+    *,
+    code: str,
+    message: str,
+    owner: str,
+) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise PzError(
+            code=code,
+            message=message,
+            stage="middlewares",
+            owner=owner,
+            action="compile_middleware_manifest",
+        )
+    return value.strip()
+
+
+def _read_optional_string(
+    value: object,
+    *,
+    default: str | None,
+    code: str,
+    message: str,
+    owner: str,
+) -> str | None:
+    if value is None:
+        return default
+    if not isinstance(value, str) or not value.strip():
+        raise PzError(
+            code=code,
+            message=message,
+            stage="middlewares",
+            owner=owner,
+            action="compile_middleware_manifest",
+        )
+    return value.strip()
+
+
+def _read_priority(
+    value: object,
+    *,
+    default: int,
+    code: str,
+    message: str,
+    owner: str,
+) -> int:
+    if value is None:
+        return int(default)
+    if isinstance(value, bool):
+        raise PzError(
+            code=code,
+            message=message,
+            stage="middlewares",
+            owner=owner,
+            action="compile_middleware_manifest",
+        )
+    if isinstance(value, int):
+        return int(value)
+    if isinstance(value, str) and value.strip():
+        try:
+            return int(value.strip())
+        except ValueError as exc:
+            raise PzError(
+                code=code,
+                message=message,
+                stage="middlewares",
+                owner=owner,
+                action="compile_middleware_manifest",
+            ) from exc
+    raise PzError(
+        code=code,
+        message=message,
+        stage="middlewares",
+        owner=owner,
+        action="compile_middleware_manifest",
+    )
+
+
+def _normalize_import_path(import_path: object, *, owner: str) -> str:
+    value = _read_required_string(
+        import_path,
+        code="PZ_MIDDLEWARE_IMPORT_INVALID",
+        message=f"Middleware '{owner}' must declare import/factory as a non-empty string path.",
+        owner=owner,
+    )
+    if ":" in value:
+        module_name, _, attr_name = value.partition(":")
+    else:
+        module_name, _, attr_name = value.rpartition(".")
+    if not module_name or not attr_name:
+        raise PzError(
+            code="PZ_MIDDLEWARE_IMPORT_INVALID",
+            message=f"Middleware import path '{import_path}' must use '<module>:<attr>' format.",
+            stage="middlewares",
+            owner=owner,
+            action="compile_middleware_manifest",
+        )
+    return f"{module_name}:{attr_name}"
+
+
+def _normalize_validated_params(
+    validated: object,
+    raw_params: Mapping[str, Any],
+    *,
+    middleware_id: str,
+    owner: str,
+) -> dict[str, Any]:
+    if validated is None:
+        return {}
+    model_dump = getattr(validated, "model_dump", None)
+    if callable(model_dump):
+        payload = model_dump()
+        if isinstance(payload, dict):
+            return dict(payload)
+    dict_method = getattr(validated, "dict", None)
+    if callable(dict_method):
+        payload = dict_method()
+        if isinstance(payload, dict):
+            return dict(payload)
+    if is_dataclass(validated):
+        payload = asdict(validated)
+        if isinstance(payload, dict):
+            return dict(payload)
+    if isinstance(validated, Mapping):
+        return dict(validated)
+    extracted: dict[str, Any] = {}
+    for key in raw_params:
+        if hasattr(validated, key):
+            extracted[str(key)] = getattr(validated, key)
+    if len(extracted) == len(raw_params):
+        return extracted
+    try:
+        payload = vars(validated)
+    except TypeError as exc:
+        raise PzError(
+            code="PZ_MIDDLEWARE_PARAMS_INVALID",
+            message=(
+                f"Middleware '{middleware_id}' params_model must expose normalized params via "
+                "model_dump(), dict(), dataclass fields, Mapping semantics, or matching attributes."
+            ),
+            stage="middlewares",
+            owner=owner,
+            action="compile_middleware_manifest",
+        ) from exc
+    if isinstance(payload, dict):
+        return dict(payload)
+    raise PzError(
+        code="PZ_MIDDLEWARE_PARAMS_INVALID",
+        message=(
+            f"Middleware '{middleware_id}' params_model must expose normalized params via "
+            "model_dump(), dict(), dataclass fields, Mapping semantics, or matching attributes."
+        ),
+        stage="middlewares",
+        owner=owner,
+        action="compile_middleware_manifest",
+    )
+
+
+def _validate_params_model(
+    params_model_path: str | None,
+    params: dict[str, Any] | None,
+    *,
+    owner: str,
+    middleware_id: str,
+) -> dict[str, Any] | None:
+    if not params:
+        return None
+    if not params_model_path:
+        raise PzError(
+            code="PZ_MIDDLEWARE_PARAMS_MODEL_MISSING",
+            message=(
+                f"Middleware '{middleware_id}' declares params but does not declare a params_model."
+            ),
+            stage="middlewares",
+            owner=owner,
+            action="compile_middleware_manifest",
+        )
+    try:
+        module_name, _, attr_name = _normalize_import_path(params_model_path, owner=middleware_id).partition(":")
+        params_model = getattr(__import__(module_name, fromlist=[attr_name]), attr_name)
+        validated = params_model(**params)
+        return _normalize_validated_params(validated, params, middleware_id=middleware_id, owner=owner)
+    except PzError:
+        raise
+    except Exception as exc:
+        raise PzError(
+            code="PZ_MIDDLEWARE_PARAMS_INVALID",
+            message=f"Middleware '{middleware_id}' params failed validation: {exc}",
+            stage="middlewares",
+            owner=owner,
+            action="compile_middleware_manifest",
+        ) from exc
+
+
+def _compile_decl(item: object, idx: int, *, owner_hint: str = "runtime") -> MiddlewareDecl | None:
+    if isinstance(item, MiddlewareDecl):
+        return item
+    if isinstance(item, str):
+        factory = item.strip()
+        owner = owner_hint
+        mid = f"middleware_{idx}"
+        priority = 100
+        replace = None
+        params_model = None
+        params = None
+    elif isinstance(item, dict):
+        owner = _read_optional_string(
+            item.get("owner"),
+            default=owner_hint,
+            code="PZ_MIDDLEWARE_OWNER_INVALID",
+            message="Middleware owner must be a non-empty string when provided.",
+            owner="runtime.middlewares",
+        ) or owner_hint
+        mid = _read_optional_string(
+            item.get("id"),
+            default=f"middleware_{idx}",
+            code="PZ_MIDDLEWARE_ID_INVALID",
+            message="Middleware id must be a non-empty string when provided.",
+            owner=owner,
+        ) or f"middleware_{idx}"
+        priority = _read_priority(
+            item.get("priority"),
+            default=100,
+            code="PZ_MIDDLEWARE_PRIORITY_INVALID",
+            message=f"Middleware '{mid}' priority must be an integer when provided.",
+            owner=owner,
+        )
+        factory = _read_optional_string(
+            item.get("factory"),
+            default=None,
+            code="PZ_MIDDLEWARE_IMPORT_INVALID",
+            message=f"Middleware '{mid}' factory must be a non-empty string when provided.",
+            owner=owner,
+        )
+        replace = _read_optional_string(
+            item.get("replace"),
+            default=None,
+            code="PZ_MIDDLEWARE_REPLACE_INVALID",
+            message=f"Middleware '{mid}' replace target must be a non-empty string when provided.",
+            owner=owner,
+        )
+        params_model = _read_optional_string(
+            item.get("params_model"),
+            default=None,
+            code="PZ_MIDDLEWARE_PARAMS_MODEL_INVALID",
+            message=f"Middleware '{mid}' params_model must be a non-empty string when provided.",
+            owner=owner,
+        )
+        raw_params = item.get("params")
+        if raw_params in (None, {}):
+            params = None
+        elif not isinstance(raw_params, dict):
+            raise PzError(
+                code="PZ_MIDDLEWARE_PARAMS_INVALID",
+                message=f"Middleware '{mid}' params must be a table.",
+                stage="middlewares",
+                owner=owner,
+                action="compile_middleware_manifest",
+            )
+        else:
+            params = dict(raw_params)
+    else:
+        raise PzError(
+            code="PZ_MIDDLEWARE_ITEM_INVALID",
+            message="Each middleware declaration must be a string import path or a table.",
+            stage="middlewares",
+            owner="runtime.middlewares",
+            action="compile_middleware_manifest",
+        )
+    if not factory:
+        raise PzError(
+            code="PZ_MIDDLEWARE_IMPORT_INVALID",
+            message=f"Middleware '{mid}' must declare a non-empty import/factory path.",
+            stage="middlewares",
+            owner=owner,
+            action="compile_middleware_manifest",
+        )
+    factory = _normalize_import_path(factory, owner=mid)
+    params = _validate_params_model(params_model, params, owner=owner, middleware_id=mid)
+    return MiddlewareDecl(
+        id=mid,
+        factory=factory,
+        owner=owner,
+        priority=priority,
+        replace=replace,
+        params_model=params_model,
+        params=params,
+    )
+
+
+def _load_app_declared_middlewares(
+    settings: SettingsSnapshot,
+    app_registry: AppRegistry,
+) -> tuple[object, ...]:
+    out: list[object] = []
+    for app in app_registry.apps:
+        static_decl = read_static_app_declaration(
+            app.module_path,
+            action="compile_middleware_manifest",
+        )
+        if "middlewares" not in static_decl.method_names:
+            continue
+        app_obj = load_app_entrypoint_object_from_decl(app)
+        middlewares_factory = getattr(app_obj, "middlewares", None)
+        if middlewares_factory is None:
+            continue
+        if not callable(middlewares_factory):
+            raise PzError(
+                code="PZ_APP_MIDDLEWARES_INVALID",
+                message=f"App '{app.app_id}' exposes non-callable middlewares().",
+                stage="middlewares",
+                owner=app.app_id,
+                action="compile_middleware_manifest",
+            )
+        signature = inspect.signature(middlewares_factory)
+        if len(signature.parameters) == 0:
+            declared = middlewares_factory()
+        else:
+            declared = middlewares_factory(settings)
+        if declared in (None, (), []):
+            continue
+        if not isinstance(declared, (list, tuple)):
+            raise PzError(
+                code="PZ_APP_MIDDLEWARES_INVALID",
+                message=f"App '{app.app_id}' middlewares() must return a list or tuple.",
+                stage="middlewares",
+                owner=app.app_id,
+                action="compile_middleware_manifest",
+            )
+        for item in declared:
+            if not isinstance(item, MiddlewareDecl):
+                raise PzError(
+                    code="PZ_APP_MIDDLEWARE_DECL_INVALID",
+                    message=(
+                        f"App '{app.app_id}' middlewares() must return MiddlewareDecl objects. "
+                        "Legacy string/table declarations are not accepted in app code."
+                    ),
+                    stage="middlewares",
+                    owner=app.app_id,
+                    action="compile_middleware_manifest",
+                )
+            out.append((app.app_id, item))
+    return tuple(out)
+
+
+def sort_middleware_declarations(
+    declarations: tuple[tuple[str, object], ...],
+) -> MiddlewareManifest:
+    out: list[MiddlewareDecl] = []
+    active_ids: dict[str, int] = {}
+
+    for idx, (owner_hint, item) in enumerate(declarations):
+        decl = _compile_decl(item, idx, owner_hint=owner_hint)
+        if decl is None:
+            continue
+        if decl.replace:
+            replaced_idx = active_ids.get(decl.replace)
+            if replaced_idx is None:
+                raise PzError(
+                    code="PZ_MIDDLEWARE_REPLACE_TARGET_MISSING",
+                    message=(
+                        f"Middleware '{decl.id}' cannot replace missing middleware "
+                        f"'{decl.replace}'."
+                    ),
+                    stage="middlewares",
+                    owner=decl.owner,
+                    action="compile_middleware_manifest",
+                )
+            out.pop(replaced_idx)
+            active_ids = {item.id: current for current, item in enumerate(out)}
+
+        current_idx = active_ids.get(decl.id)
+        if current_idx is not None:
+            previous = out[current_idx]
+            raise PzError(
+                code="PZ_MIDDLEWARE_DUPLICATE_ID",
+                message=(
+                    f"Middleware id '{decl.id}' is declared more than once "
+                    f"by owners '{previous.owner}' and '{decl.owner}'."
+                ),
+                stage="middlewares",
+                owner=decl.owner,
+                action="compile_middleware_manifest",
+            )
+        out.append(decl)
+        active_ids[decl.id] = len(out) - 1
+    return MiddlewareManifest(middlewares=tuple(out))
+
+
+def compile_conventional_middleware_manifest(
+    settings: SettingsSnapshot,
+    app_registry: AppRegistry,
+) -> MiddlewareManifest:
+    project_dir = getattr(settings, "project_dir", None)
+    import_roots = getattr(settings, "import_roots", ())
+    with active_project_import_root(
+        project_dir,
+        extra_import_roots=import_roots,
+    ):
+        owner_order = {app.app_id: idx for idx, app in enumerate(app_registry.apps)}
+        declarations = list(_load_app_declared_middlewares(settings, app_registry))
+    declarations.sort(
+        key=lambda item: (
+            int(100 if getattr(item[1], "priority", 100) is None else getattr(item[1], "priority", 100)),
+            owner_order.get(item[0], len(owner_order)),
+            str(getattr(item[1], "id", "") or ""),
+        )
+    )
+    return sort_middleware_declarations(tuple(declarations))
+
+
+def merge_explicit_middleware_order(
+    existing_ids: tuple[str, ...] | list[str],
+    conventional_manifest: MiddlewareManifest,
+) -> MiddlewareManifest:
+    conventional_ids = tuple(item.id for item in conventional_manifest.middlewares)
+    conventional_set = set(conventional_ids)
+    existing: list[str] = []
+    seen_existing: set[str] = set()
+    for item in existing_ids:
+        candidate = str(item).strip()
+        if not candidate or candidate not in conventional_set or candidate in seen_existing:
+            continue
+        existing.append(candidate)
+        seen_existing.add(candidate)
+    existing = tuple(existing)
+    if not existing:
+        return conventional_manifest
+
+    by_id = {item.id: item for item in conventional_manifest.middlewares}
+    existing_set = set(existing)
+    ordered_ids = list(existing)
+    for index, candidate in enumerate(conventional_ids):
+        if candidate in existing_set:
+            continue
+        anchor: str | None = None
+        for following in conventional_ids[index + 1 :]:
+            if following in existing_set:
+                anchor = following
+                break
+        if anchor is None:
+            ordered_ids.append(candidate)
+            continue
+        ordered_ids.insert(ordered_ids.index(anchor), candidate)
+    return MiddlewareManifest(middlewares=tuple(by_id[item_id] for item_id in ordered_ids))
+
+
+def compile_middleware_manifest(
+    settings: SettingsSnapshot,
+    app_registry: AppRegistry | None = None,
+) -> MiddlewareManifest:
+    raw_middlewares = settings.get("middlewares", default=[])
+    if not isinstance(raw_middlewares, list):
+        raise PzError(
+            code="PZ_MIDDLEWARES_CONFIG_INVALID",
+            message="middlewares must be declared as an array of middleware declarations.",
+            stage="middlewares",
+            owner="runtime.middlewares",
+            action="compile_middleware_manifest",
+        )
+
+    explicit_manifest = sort_middleware_declarations(tuple(("runtime", item) for item in raw_middlewares))
+    if app_registry is None:
+        return explicit_manifest
+
+    conventional_manifest = compile_conventional_middleware_manifest(settings, app_registry)
+    if not explicit_manifest.middlewares:
+        return conventional_manifest
+
+    explicit_by_id = {item.id: item for item in explicit_manifest.middlewares}
+    explicit_ids = tuple(item.id for item in explicit_manifest.middlewares)
+    explicit_set = set(explicit_ids)
+    merged_ids = list(explicit_ids)
+    conventional_ids = tuple(item.id for item in conventional_manifest.middlewares)
+    for index, candidate in enumerate(conventional_ids):
+        if candidate in explicit_set:
+            continue
+        anchor: str | None = None
+        for following in conventional_ids[index + 1 :]:
+            if following in explicit_set:
+                anchor = following
+                break
+        if anchor is None:
+            merged_ids.append(candidate)
+            continue
+        merged_ids.insert(merged_ids.index(anchor), candidate)
+    conventional_by_id = {item.id: item for item in conventional_manifest.middlewares}
+    merged: list[MiddlewareDecl] = [
+        explicit_by_id[item_id] if item_id in explicit_by_id else conventional_by_id[item_id]
+        for item_id in merged_ids
+    ]
+    return MiddlewareManifest(middlewares=tuple(merged))

pz_core/assembly/project/__init__.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from .context import ProjectContext
+from .compiler import compile_project_context
+from .discovery import active_project_import_root, resolve_project_context
+
+__all__ = ["ProjectContext", "active_project_import_root", "compile_project_context", "resolve_project_context"]

pz_core/assembly/project/compiler.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+import os
+from pz_core.assembly.project.context import ProjectContext
+from pz_core.assembly.project.discovery import resolve_project_context
+
+
+def compile_project_context(project_dir: str | os.PathLike[str] | None = None) -> ProjectContext:
+    return resolve_project_context(project_dir=project_dir)

pz_core/assembly/project/context.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True, slots=True)
+class ProjectContext:
+    project_dir: Path
+    project_config_path: Path
+    env_file_path: Path
+    cache_dir: Path
+    runtime_dir: Path
+    asset_dir: Path
+
+
+__all__ = ["ProjectContext"]