pz-cli 5.0.0__py3-none-any.whl

pz_core/utils/project_jsonc/document.py

@@ -0,0 +1,420 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+from pathlib import Path
+import re
+from typing import Any, Iterable
+
+from pz_core.core.errors import PzError
+
+
+PROJECT_JSONC_NAME = "pz.jsonc"
+TOOL_COMMENT_PREFIX = "@pz:"
+MANAGED_START_DIRECTIVE = "managed:start"
+MANAGED_END_DIRECTIVE = "managed:end"
+INLINE_ARRAY_MAX_LINE_LENGTH = 100
+_TOOL_COMMENT_PATTERN = re.compile(r"^\s*//\s*@pz:(?P<directive>[A-Za-z0-9:_-]+)(?:\s+(?P<payload>.+?))?\s*$")
+
+
+@dataclass(frozen=True, slots=True)
+class ToolComment:
+    directive: str
+    payload: str | None = None
+
+
+def parse_tool_comment(line: str) -> ToolComment | None:
+    match = _TOOL_COMMENT_PATTERN.match(line)
+    if match is None:
+        return None
+    payload = match.group("payload")
+    return ToolComment(
+        directive=str(match.group("directive") or "").strip(),
+        payload=payload.strip() if isinstance(payload, str) and payload.strip() else None,
+    )
+
+
+def normalize_jsonc_path(path: str | Iterable[str]) -> tuple[str, ...]:
+    if isinstance(path, str):
+        tokens = tuple(part.strip() for part in path.split(".") if part.strip())
+    else:
+        tokens = tuple(str(part).strip() for part in path if str(part).strip())
+    if not tokens:
+        raise PzError(
+            code="PZ_PROJECT_JSONC_PATH_INVALID",
+            message="JSONC path must contain at least one non-empty segment.",
+            stage="settings",
+            owner="project_jsonc",
+            action="normalize_path",
+        )
+    return tokens
+
+
+def set_jsonc_path(mapping: dict[str, Any], path: str | Iterable[str], value: Any) -> None:
+    segments = normalize_jsonc_path(path)
+    current = mapping
+    for segment in segments[:-1]:
+        child = current.get(segment)
+        if not isinstance(child, dict):
+            child = {}
+            current[segment] = child
+        current = child
+    current[segments[-1]] = value
+
+
+def load_jsonc_file(
+    path: str | Path,
+    *,
+    code: str = "PZ_PROJECT_CONFIG_INVALID",
+    owner: str = "project_jsonc",
+    action: str = "load_jsonc",
+) -> dict[str, Any]:
+    resolved = Path(path).expanduser().resolve()
+    if not resolved.is_file():
+        return {}
+    raw = resolved.read_text(encoding="utf-8")
+    return load_jsonc_text(
+        raw,
+        code=code,
+        owner=owner,
+        action=action,
+        source_name=resolved.name,
+        source_path=resolved,
+    )
+
+
+def load_jsonc_text(
+    text: str,
+    *,
+    code: str = "PZ_PROJECT_CONFIG_INVALID",
+    owner: str = "project_jsonc",
+    action: str = "load_jsonc",
+    source_name: str = "<memory>",
+    source_path: str | Path | None = None,
+) -> dict[str, Any]:
+    try:
+        payload = json.loads(_prepare_json_text(text))
+    except json.JSONDecodeError as exc:
+        raise PzError(
+            code=code,
+            message=f"Invalid JSONC in '{source_name}'.",
+            stage="settings",
+            owner=owner,
+            action=action,
+            summary=f"Invalid JSONC in '{source_name}'.",
+            detail=f"{source_path or source_name}: {exc}",
+        ) from exc
+    if not isinstance(payload, dict):
+        raise PzError(
+            code=code,
+            message=f"Project config '{source_name}' must define a JSON object payload.",
+            stage="settings",
+            owner=owner,
+            action=action,
+        )
+    return payload
+
+
+def dump_jsonc_document(
+    payload: dict[str, Any],
+    *,
+    managed_paths: Iterable[str | Iterable[str]] = (),
+    comments: dict[str | tuple[str, ...], Iterable[str]] | None = None,
+) -> str:
+    normalized_managed_paths = {normalize_jsonc_path(path) for path in managed_paths}
+    normalized_comments = _normalize_comments(comments or {})
+    lines = _render_object(
+        payload,
+        indent=0,
+        path=(),
+        managed_paths=normalized_managed_paths,
+        comments=normalized_comments,
+    )
+    return "\n".join(lines) + "\n"
+
+
+def _normalize_comments(comments: dict[str | tuple[str, ...], Iterable[str]]) -> dict[tuple[str, ...], tuple[str, ...]]:
+    normalized: dict[tuple[str, ...], tuple[str, ...]] = {}
+    for raw_path, raw_lines in comments.items():
+        path = normalize_jsonc_path(raw_path)
+        lines = tuple(str(line).strip() for line in raw_lines if str(line).strip())
+        if lines:
+            normalized[path] = lines
+    return normalized
+
+
+def _comment_lines(path: tuple[str, ...], *, indent: int, comments: dict[tuple[str, ...], tuple[str, ...]]) -> list[str]:
+    lines = comments.get(path, ())
+    if not lines:
+        return []
+    indent_str = "  " * indent
+    return [indent_str + "// " + line for line in lines]
+
+
+def _prepare_json_text(text: str) -> str:
+    return _strip_trailing_commas(_strip_jsonc_comments(text))
+
+
+def _strip_jsonc_comments(text: str) -> str:
+    chars: list[str] = []
+    index = 0
+    in_string = False
+    string_quote = ""
+    in_line_comment = False
+    in_block_comment = False
+    escaped = False
+    length = len(text)
+
+    while index < length:
+        char = text[index]
+        next_char = text[index + 1] if index + 1 < length else ""
+
+        if in_line_comment:
+            if char == "\n":
+                in_line_comment = False
+                chars.append(char)
+            index += 1
+            continue
+
+        if in_block_comment:
+            if char == "*" and next_char == "/":
+                in_block_comment = False
+                index += 2
+                continue
+            if char == "\n":
+                chars.append(char)
+            index += 1
+            continue
+
+        if in_string:
+            chars.append(char)
+            if escaped:
+                escaped = False
+            elif char == "\\":
+                escaped = True
+            elif char == string_quote:
+                in_string = False
+                string_quote = ""
+            index += 1
+            continue
+
+        if char == "/" and next_char == "/":
+            in_line_comment = True
+            index += 2
+            continue
+        if char == "/" and next_char == "*":
+            in_block_comment = True
+            index += 2
+            continue
+        if char in {'"', "'"}:
+            in_string = True
+            string_quote = char
+            chars.append(char)
+            index += 1
+            continue
+
+        chars.append(char)
+        index += 1
+
+    return "".join(chars)
+
+
+def _strip_trailing_commas(text: str) -> str:
+    chars: list[str] = []
+    in_string = False
+    string_quote = ""
+    escaped = False
+    length = len(text)
+    index = 0
+
+    while index < length:
+        char = text[index]
+        if in_string:
+            chars.append(char)
+            if escaped:
+                escaped = False
+            elif char == "\\":
+                escaped = True
+            elif char == string_quote:
+                in_string = False
+                string_quote = ""
+            index += 1
+            continue
+
+        if char in {'"', "'"}:
+            in_string = True
+            string_quote = char
+            chars.append(char)
+            index += 1
+            continue
+
+        if char == ",":
+            lookahead = index + 1
+            while lookahead < length and text[lookahead] in {" ", "\t", "\r", "\n"}:
+                lookahead += 1
+            if lookahead < length and text[lookahead] in {"]", "}"}:
+                index += 1
+                continue
+
+        chars.append(char)
+        index += 1
+
+    return "".join(chars)
+
+
+def _render_object(
+    payload: dict[str, Any],
+    *,
+    indent: int,
+    path: tuple[str, ...],
+    managed_paths: set[tuple[str, ...]],
+    comments: dict[tuple[str, ...], tuple[str, ...]],
+) -> list[str]:
+    indent_str = "  " * indent
+    if not payload:
+        return [indent_str + "{}"]
+    lines = [indent_str + "{"]
+    items = list(payload.items())
+    for index, (key, value) in enumerate(items):
+        is_last = index == len(items) - 1
+        property_path = path + (key,)
+        lines.extend(_comment_lines(property_path, indent=indent + 1, comments=comments))
+        if property_path in managed_paths:
+            lines.append("  " * (indent + 1) + f"// @pz:{MANAGED_START_DIRECTIVE} {'.'.join(property_path)}")
+        lines.extend(
+            _render_property(
+                key,
+                value,
+                indent=indent + 1,
+                is_last=is_last,
+                path=property_path,
+                managed_paths=managed_paths,
+                comments=comments,
+            )
+        )
+        if property_path in managed_paths:
+            lines.append("  " * (indent + 1) + f"// @pz:{MANAGED_END_DIRECTIVE} {'.'.join(property_path)}")
+    lines.append(indent_str + "}")
+    return lines
+
+
+def _render_property(
+    key: str,
+    value: Any,
+    *,
+    indent: int,
+    is_last: bool,
+    path: tuple[str, ...],
+    managed_paths: set[tuple[str, ...]],
+    comments: dict[tuple[str, ...], tuple[str, ...]],
+) -> list[str]:
+    indent_str = "  " * indent
+    key_text = json.dumps(key, ensure_ascii=False)
+    suffix = "" if is_last else ","
+    if isinstance(value, dict):
+        if not value:
+            return [indent_str + f"{key_text}: {{}}{suffix}"]
+        lines = [indent_str + f"{key_text}: {{"]
+        items = list(value.items())
+        for index, (child_key, child_value) in enumerate(items):
+            child_is_last = index == len(items) - 1
+            child_path = path + (child_key,)
+            lines.extend(_comment_lines(child_path, indent=indent + 1, comments=comments))
+            if child_path in managed_paths:
+                lines.append("  " * (indent + 1) + f"// @pz:{MANAGED_START_DIRECTIVE} {'.'.join(child_path)}")
+            lines.extend(
+                _render_property(
+                    child_key,
+                    child_value,
+                    indent=indent + 1,
+                    is_last=child_is_last,
+                    path=child_path,
+                    managed_paths=managed_paths,
+                    comments=comments,
+                )
+            )
+            if child_path in managed_paths:
+                lines.append("  " * (indent + 1) + f"// @pz:{MANAGED_END_DIRECTIVE} {'.'.join(child_path)}")
+        lines.append(indent_str + "}" + suffix)
+        return lines
+    if isinstance(value, (list, tuple)):
+        return _render_array_property(key_text, list(value), indent=indent, is_last=is_last)
+    return [indent_str + f"{key_text}: {_format_scalar(value)}{suffix}"]
+
+
+def _render_array_property(key_text: str, items: list[Any], *, indent: int, is_last: bool) -> list[str]:
+    indent_str = "  " * indent
+    suffix = "" if is_last else ","
+    if not items:
+        return [indent_str + f"{key_text}: []{suffix}"]
+    inline_array = _format_inline_array(items)
+    if inline_array is not None:
+        inline_line = indent_str + f"{key_text}: {inline_array}{suffix}"
+        if len(inline_line) <= INLINE_ARRAY_MAX_LINE_LENGTH:
+            return [inline_line]
+    lines = [indent_str + f"{key_text}: ["]
+    for index, item in enumerate(items):
+        lines.extend(_render_array_item(item, indent=indent + 1, is_last=index == len(items) - 1))
+    lines.append(indent_str + "]" + suffix)
+    return lines
+
+
+def _render_array_item(value: Any, *, indent: int, is_last: bool) -> list[str]:
+    indent_str = "  " * indent
+    suffix = "" if is_last else ","
+    if isinstance(value, dict):
+        if not value:
+            return [indent_str + "{}" + suffix]
+        lines = [indent_str + "{"]
+        items = list(value.items())
+        for index, (key, item_value) in enumerate(items):
+            lines.extend(
+                _render_property(
+                    key,
+                    item_value,
+                    indent=indent + 1,
+                    is_last=index == len(items) - 1,
+                    path=(str(index), key),
+                    managed_paths=set(),
+                    comments={},
+                )
+            )
+        lines.append(indent_str + "}" + suffix)
+        return lines
+    if isinstance(value, (list, tuple)):
+        value = list(value)
+        if not value:
+            return [indent_str + "[]" + suffix]
+        lines = [indent_str + "["]
+        for index, item in enumerate(value):
+            lines.extend(_render_array_item(item, indent=indent + 1, is_last=index == len(value) - 1))
+        lines.append(indent_str + "]" + suffix)
+        return lines
+    return [indent_str + _format_scalar(value) + suffix]
+
+
+def _format_scalar(value: Any) -> str:
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return json.dumps(value, ensure_ascii=False)
+    if isinstance(value, str):
+        return json.dumps(value, ensure_ascii=False)
+    raise PzError(
+        code="PZ_PROJECT_JSONC_VALUE_INVALID",
+        message=f"Unsupported JSONC value type: {type(value).__name__}",
+        stage="settings",
+        owner="project_jsonc",
+        action="dump_jsonc",
+    )
+
+
+def _format_inline_array(items: list[Any]) -> str | None:
+    rendered_items: list[str] = []
+    for item in items:
+        if isinstance(item, (dict, list, tuple)):
+            return None
+        rendered_items.append(_format_scalar(item))
+    return "[" + ", ".join(rendered_items) + "]"

pz_core/utils/project_settings.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class HostProjectShortcuts:
+    app_host: str
+    app_port: int
+    app_reload: bool
+    app_workers: int
+
+
+def resolve_project_dir(anchor: str | Path | None = None) -> Path:
+    from pz_core.assembly.project import resolve_project_context
+
+    project = resolve_project_context()
+    if project.project_config_path.is_file():
+        return project.project_dir
+    if anchor is None:
+        return project.project_dir
+    return Path(anchor).expanduser().resolve().parent
+
+
+def _project_settings_snapshot(*, project_dir: str | Path | None = None):
+    from pz_core.assembly.project.compiler import compile_project_context
+    from pz_core.assembly.settings.compiler import compile_settings_snapshot
+
+    project = compile_project_context(project_dir=project_dir)
+    return compile_settings_snapshot(project)
+
+
+def _project_value(
+    name: str, default: Any, *, project_dir: str | Path | None = None
+) -> Any:
+    try:
+        return _project_settings_snapshot(project_dir=project_dir).get(
+            "project", str(name).strip(), default=default
+        )
+    except Exception:
+        return default
+
+
+def _project_int(
+    name: str, default: int, *, project_dir: str | Path | None = None
+) -> int:
+    value = _project_value(name, default, project_dir=project_dir)
+    try:
+        return int(value)
+    except Exception:
+        return int(default)
+
+
+def _project_bool(
+    name: str, default: bool, *, project_dir: str | Path | None = None
+) -> bool:
+    value = _project_value(name, default, project_dir=project_dir)
+    if isinstance(value, bool):
+        return value
+    if value is None:
+        return bool(default)
+    return str(value).strip().lower() in {"1", "true", "yes", "on"}
+
+
+def resolve_host_project_shortcuts(
+    *, project_dir: str | Path | None = None
+) -> HostProjectShortcuts:
+    return HostProjectShortcuts(
+        app_host=str(
+            _project_value("app_host", "0.0.0.0", project_dir=project_dir) or "0.0.0.0"
+        ).strip()
+        or "0.0.0.0",
+        app_port=_project_int("app_port", 8000, project_dir=project_dir),
+        app_reload=_project_bool("app_reload", False, project_dir=project_dir),
+        app_workers=max(1, _project_int("app_workers", 1, project_dir=project_dir)),
+    )
+
+
+def resolve_host_reload_dirs(*, project_dir: str | Path) -> list[str]:
+    from pz_core.assembly.app_discovery import iter_visible_app_projections
+
+    root = Path(project_dir).expanduser().resolve()
+    apps_dir = root / "apps"
+    if not apps_dir.is_dir():
+        return [str(root)]
+    return [
+        str(projection.visible_root)
+        for projection in iter_visible_app_projections(root)
+    ]
+
+
+__all__ = [
+    "HostProjectShortcuts",
+    "resolve_host_reload_dirs",
+    "resolve_host_project_shortcuts",
+    "resolve_project_dir",
+]

pz_foundation/__init__.py

@@ -0,0 +1,50 @@
+"""Canonical package interface for foundation capabilities."""
+
+from __future__ import annotations
+
+from importlib import import_module
+
+_EXPORTS = {
+    "CacheFacade": ("pz_foundation.public", "CacheFacade"),
+    "DatabaseFacade": ("pz_foundation.public", "DatabaseFacade"),
+    "FoundationFacade": ("pz_foundation.public", "FoundationFacade"),
+    "HealthFacade": ("pz_foundation.public", "HealthFacade"),
+    "MailFacade": ("pz_foundation.public", "MailFacade"),
+    "ObservabilityFacade": ("pz_foundation.public", "ObservabilityFacade"),
+    "StorageFacade": ("pz_foundation.public", "StorageFacade"),
+    "build_local_typed_settings": ("pz_foundation.public", "build_local_typed_settings"),
+    "build_typed_settings_from_namespace": ("pz_foundation.public", "build_typed_settings_from_namespace"),
+    "get_foundation_facade": ("pz_foundation.public", "get_foundation_facade"),
+    "install_lazy_callables": ("pz_foundation.lazy_imports", "install_lazy_callables"),
+    "LazyCallableProxy": ("pz_foundation.lazy_imports", "LazyCallableProxy"),
+    "LazyImportProxy": ("pz_foundation.lazy_imports", "LazyImportProxy"),
+    "lazy_import_attr": ("pz_foundation.lazy_imports", "lazy_import_attr"),
+    "lazy_import_factory": ("pz_foundation.lazy_imports", "lazy_import_factory"),
+    "normalize_settings_payload_keys": ("pz_foundation.public", "normalize_settings_payload_keys"),
+    "resolve_typed_app_settings": ("pz_foundation.public", "resolve_typed_app_settings"),
+    "FoundationDatabase": ("pz_foundation.db", "FoundationDatabase"),
+    "FoundationDatabaseSettings": ("pz_foundation.db", "FoundationDatabaseSettings"),
+    "MySQLFoundationDatabase": ("pz_foundation.db", "MySQLFoundationDatabase"),
+    "PostgreSQLFoundationDatabase": ("pz_foundation.db", "PostgreSQLFoundationDatabase"),
+    "SQLiteFoundationDatabase": ("pz_foundation.db", "SQLiteFoundationDatabase"),
+    "build_foundation_connections": ("pz_foundation.db", "build_foundation_connections"),
+    "build_foundation_tortoise_config": ("pz_foundation.db", "build_foundation_tortoise_config"),
+    "get_foundation_database": ("pz_foundation.db", "get_foundation_database"),
+    "get_foundation_database_if_enabled": ("pz_foundation.db", "get_foundation_database_if_enabled"),
+    "get_foundation_tortoise_config": ("pz_foundation.db", "get_foundation_tortoise_config"),
+    "load_foundation_database_settings": ("pz_foundation.db", "load_foundation_database_settings"),
+    "reset_foundation_databases": ("pz_foundation.db", "reset_foundation_databases"),
+}
+
+__all__ = sorted(_EXPORTS)
+
+
+def __getattr__(name: str):
+    target = _EXPORTS.get(name)
+    if target is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    module_name, attr_name = target
+    module = import_module(module_name)
+    value = getattr(module, attr_name)
+    globals()[name] = value
+    return value

pz_foundation/_contracts.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Protocol, runtime_checkable
+
+
+@dataclass(frozen=True, slots=True)
+class PresignInfo:
+    method: str
+    url: str
+    expires_in_seconds: int
+
+
+@dataclass(frozen=True, slots=True)
+class StoredObject:
+    object_key: str
+    size: int | None = None
+    content_type: str | None = None
+
+
+@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: ...
+
+
+@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: ...
+
+
+@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_foundation/_errors.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(slots=True)
+class FoundationError(Exception):
+    code: str
+    message: str
+    stage: str
+    owner: str
+    action: str
+    summary: str | None = None
+    detail: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        payload = {
+            "code": self.code,
+            "message": self.message,
+            "summary": self.summary or self.message,
+            "stage": self.stage,
+            "owner": self.owner,
+            "action": self.action,
+        }
+        if self.detail:
+            payload["detail"] = self.detail
+        return payload
+
+    def __str__(self) -> str:
+        summary = self.summary or self.message
+        if self.detail:
+            return f"[{self.code}] {summary}: {self.detail}"
+        return f"[{self.code}] {summary}"

pz_foundation/api.py

@@ -0,0 +1,14 @@
+"""Formal API surface for foundation runtime helpers outside the stable public facade."""
+
+from __future__ import annotations
+
+from .lazy_imports import lazy_import_attr
+from .lazy_exports import export_dir, resolve_lazy_export
+from .resources.builder import build_resource_manifest
+
+__all__ = [
+    "build_resource_manifest",
+    "export_dir",
+    "lazy_import_attr",
+    "resolve_lazy_export",
+]