pz-cli 5.0.0__py3-none-any.whl

pz_core/runtime/worker/runtime.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from .engine import (
+    WorkerControl,
+    WorkerInvocation,
+    WorkerRuntime,
+    WorkerSession,
+    build_worker_status,
+    create_worker_runtime,
+    run_worker_entry,
+)
+from . import engine as _engine
+
+signal = _engine.signal
+
+__all__ = [
+    "WorkerControl",
+    "WorkerInvocation",
+    "WorkerRuntime",
+    "WorkerSession",
+    "build_worker_status",
+    "create_worker_runtime",
+    "run_worker_entry",
+    "signal",
+]

pz_core/testing/__init__.py

@@ -0,0 +1,15 @@
+from .doc_route_contracts import (
+    find_unimplemented_doc_routes,
+    iter_doc_method_path_contracts,
+    mounted_route_methods,
+    normalize_path,
+    path_matches,
+)
+
+__all__ = [
+    "find_unimplemented_doc_routes",
+    "iter_doc_method_path_contracts",
+    "mounted_route_methods",
+    "normalize_path",
+    "path_matches",
+]

pz_core/testing/doc_route_contracts.py

@@ -0,0 +1,305 @@
+from __future__ import annotations
+
+import re
+from importlib import import_module
+from inspect import getattr_static
+from pathlib import Path
+from typing import Any
+
+from pz_core.runtime.http import create_application_runtime
+
+METHOD_PATH_RE = re.compile(r"\b(GET|POST|PUT|DELETE|PATCH)\s+`?(/api/v1/[A-Za-z0-9_./{}:-]+)")
+
+
+def normalize_path(path: str) -> str:
+    normalized = path.rstrip("`").rstrip(".,;:")
+    if normalized != "/":
+        normalized = normalized.rstrip("/")
+    return normalized
+
+
+def path_matches(route_path: str, doc_path: str) -> bool:
+    route_segments = [s for s in normalize_path(route_path).split("/") if s]
+    doc_segments = [s for s in normalize_path(doc_path).split("/") if s]
+    if len(route_segments) != len(doc_segments):
+        return False
+    for route_segment, doc_segment in zip(route_segments, doc_segments):
+        if _is_param_segment(route_segment) or _is_param_segment(doc_segment):
+            continue
+        if route_segment != doc_segment:
+            return False
+    return True
+
+
+def iter_doc_method_path_contracts(doc_root: Path) -> set[tuple[str, str]]:
+    contracts: set[tuple[str, str]] = set()
+    for markdown_file in doc_root.rglob("*.md"):
+        text = markdown_file.read_text(encoding="utf-8", errors="ignore")
+        for method, path in METHOD_PATH_RE.findall(text):
+            contracts.add((method, normalize_path(path)))
+    return contracts
+
+
+def mounted_route_methods(
+    installed_apps: tuple[str, ...] | None = None,
+    *,
+    project_dir: str | Path | None = None,
+) -> dict[str, set[str]]:
+    mapping: dict[str, set[str]] = {}
+    resolved_project_dir = _resolve_project_dir(project_dir)
+    runtime = None
+    try:
+        runtime = create_application_runtime(
+            project_dir=resolved_project_dir,
+            installed_apps=installed_apps,
+        )
+    except Exception:
+        runtime = None
+
+    http_app = getattr(runtime, "http_app", None)
+    routes = getattr(http_app, "routes", None)
+    if routes:
+        for route in routes:
+            _collect_route(mapping, route)
+
+    plan = getattr(runtime, "plan", None)
+    app_registry = getattr(plan, "app_registry", None)
+    app_decls = getattr(app_registry, "apps", None)
+    if app_decls:
+        for decl in app_decls:
+            _collect_decl_routes(mapping, decl.entrypoint)
+
+    for module_name in tuple(str(item).strip() for item in installed_apps or () if str(item).strip()):
+        _collect_installed_app_routes(mapping, module_name)
+    return mapping
+
+
+def find_unimplemented_doc_routes(
+    contracts: set[tuple[str, str]],
+    *,
+    installed_apps: tuple[str, ...] | None = None,
+    project_dir: str | Path | None = None,
+) -> list[tuple[str, str]]:
+    mounted = mounted_route_methods(installed_apps=installed_apps, project_dir=project_dir)
+    missing = [
+        (method, path)
+        for method, path in contracts
+        if not _is_contract_implemented(method, path, mounted)
+    ]
+    return sorted(missing)
+
+
+def _resolve_project_dir(project_dir: str | Path | None) -> Path:
+    if project_dir is not None:
+        return Path(project_dir).resolve()
+    for candidate in (Path.cwd(), *Path.cwd().parents):
+        if (candidate / "pz.jsonc").is_file():
+            return candidate
+    return Path.cwd().resolve()
+
+def _collect_installed_app_routes(mapping: dict[str, set[str]], module_name: str) -> None:
+    normalized_module = str(module_name or "").strip()
+    if not normalized_module:
+        return
+    loaded_app = False
+    for candidate in (f"{normalized_module}.apps", normalized_module):
+        try:
+            module = import_module(candidate)
+        except Exception:
+            continue
+        app = getattr(module, "app", None)
+        if app is None:
+            continue
+        try:
+            routers = getattr(app, "routers", lambda: ())()
+        except Exception:
+            routers = ()
+        _collect_routers(mapping, routers)
+        extensions = getattr(app, "extensions", None)
+        if callable(extensions):
+            try:
+                items = extensions() or ()
+            except Exception:
+                items = ()
+            for item in items:
+                payload = item.get("payload") if isinstance(item, dict) else getattr(item, "payload", None)
+                if not isinstance(payload, dict):
+                    continue
+                router = payload.get("router")
+                if _is_router(router):
+                    _collect_router(mapping, router)
+        loaded_app = True
+        break
+    for suffix in ("urls", "routes", "api", "internal_api"):
+        try:
+            module = import_module(f"{normalized_module}.{suffix}")
+        except Exception:
+            continue
+        _collect_module_level_routes(mapping, module)
+    if loaded_app:
+        return
+
+
+def _collect_decl_routes(mapping: dict[str, set[str]], entrypoint: str) -> None:
+    module_name, _, attr_name = str(entrypoint or "").partition(":")
+    if not module_name or not attr_name:
+        return
+    module = import_module(module_name)
+    app = getattr(module, attr_name, None)
+    if app is None:
+        return
+    try:
+        routers = getattr(app, "routers", lambda: ())()
+    except Exception:
+        routers = ()
+    _collect_routers(mapping, routers)
+    extensions = getattr(app, "extensions", None)
+    if callable(extensions):
+        try:
+            items = extensions() or ()
+        except Exception:
+            items = ()
+        for item in items:
+            if not isinstance(item, dict):
+                continue
+            payload = item.get("payload")
+            if not isinstance(payload, dict):
+                continue
+            router = payload.get("router")
+            if _is_router(router):
+                _collect_router(mapping, router)
+
+
+def _collect_routers(mapping: dict[str, set[str]], routers: Any) -> None:
+    if _is_router(routers):
+        _collect_router(mapping, routers)
+        return
+    if isinstance(routers, (list, tuple)):
+        for router in routers:
+            if _is_router(router):
+                _collect_router(mapping, router)
+
+
+def _is_router(value: Any) -> bool:
+    try:
+        routes = getattr(value, "routes", None)
+    except Exception:
+        return False
+    return isinstance(routes, (list, tuple))
+
+
+def _is_http_route(route: Any) -> bool:
+    return isinstance(getattr(route, "path", None), str) and isinstance(getattr(route, "methods", None), (set, list, tuple))
+
+
+def _is_mount_route(route: Any) -> bool:
+    return isinstance(getattr(route, "path", None), str) and hasattr(route, "app") and not _is_http_route(route)
+
+
+def _collect_router(mapping: dict[str, set[str]], router: Any, *, path_prefix: str = "") -> None:
+    for route in router.routes:
+        _collect_route(mapping, route, path_prefix=path_prefix)
+
+
+def _join_route_path(prefix: str, path: str) -> str:
+    normalized_prefix = str(prefix or "").strip() or "/"
+    normalized_path = str(path or "").strip() or "/"
+    if normalized_prefix == "/":
+        return normalized_path
+    if normalized_path.startswith(normalized_prefix):
+        return normalized_path
+    if normalized_path == "/":
+        return normalized_prefix
+    return normalized_prefix.rstrip("/") + "/" + normalized_path.lstrip("/")
+
+
+def _collect_route(
+    mapping: dict[str, set[str]],
+    route: Any,
+    *,
+    path_prefix: str = "",
+) -> None:
+    if _is_http_route(route):
+        methods = {m for m in (route.methods or set()) if m not in {"HEAD", "OPTIONS"}}
+        route_path = _join_route_path(path_prefix, route.path)
+        mapping.setdefault(normalize_path(route_path), set()).update(methods)
+        return
+    if not _is_mount_route(route):
+        return
+    mounted_app = getattr(route, "app", None)
+    if hasattr(mounted_app, "_get_app"):
+        try:
+            mounted_app = mounted_app._get_app()
+        except Exception:
+            return
+    if callable(mounted_app) and not hasattr(mounted_app, "routes"):
+        try:
+            mounted_app = mounted_app()
+        except Exception:
+            return
+    mounted_routes = getattr(mounted_app, "routes", None)
+    if not isinstance(mounted_routes, (list, tuple)):
+        return
+    mounted_prefix = _join_route_path(path_prefix, getattr(route, "path", "/"))
+    for child_route in mounted_routes:
+        _collect_route(mapping, child_route, path_prefix=mounted_prefix)
+
+
+def _collect_module_level_routes(mapping: dict[str, set[str]], module: Any) -> None:
+    exported_names = {"router", "routers", "urlpatterns", "admin_router"}
+
+    for name in exported_names:
+        try:
+            value = getattr(module, name)
+        except Exception:
+            continue
+        _collect_exported_route_value(mapping, value)
+
+    urlpatterns = getattr(module, "urlpatterns", None)
+    if isinstance(urlpatterns, (list, tuple)):
+        for item in urlpatterns:
+            _collect_exported_route_value(mapping, item)
+    for value in vars(module).values():
+        _collect_exported_route_value(mapping, value)
+
+
+def _collect_exported_route_value(mapping: dict[str, set[str]], value: Any) -> None:
+    if _is_router(value):
+        _collect_router(mapping, value)
+        return
+    try:
+        getattr_static(value, "router")
+    except (AttributeError, TypeError):
+        declared_router = None
+    else:
+        try:
+            declared_router = getattr(value, "router")
+        except Exception:
+            declared_router = None
+    if _is_router(declared_router):
+        _collect_router(mapping, declared_router, path_prefix=str(getattr(value, "path_prefix", "") or ""))
+        return
+    if isinstance(value, (list, tuple)):
+        for item in value:
+            _collect_exported_route_value(mapping, item)
+        return
+    try:
+        getattr_static(value, "path")
+    except (AttributeError, TypeError):
+        return
+    _collect_route(mapping, value)
+
+
+def _is_param_segment(segment: str) -> bool:
+    return segment.startswith("{") and segment.endswith("}")
+
+
+def _is_contract_implemented(
+    method: str,
+    path: str,
+    mounted: dict[str, set[str]],
+) -> bool:
+    for route_path, methods in mounted.items():
+        if method in methods and path_matches(route_path, path):
+            return True
+    return False

pz_core/utils/__init__.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from .env import has_env_value, iter_env_items, read_env_bool, read_env_float, read_env_int, read_env_string
+from .project_settings import (
+    HostProjectShortcuts,
+    resolve_host_project_shortcuts,
+    resolve_host_reload_dirs,
+    resolve_project_dir,
+)
+from .project_jsonc import (
+    MANAGED_END_DIRECTIVE,
+    MANAGED_START_DIRECTIVE,
+    PROJECT_JSONC_NAME,
+    TOOL_COMMENT_PREFIX,
+    ToolComment,
+    dump_jsonc_document,
+    load_jsonc_file,
+    normalize_jsonc_path,
+    parse_tool_comment,
+    set_jsonc_path,
+)
+
+__all__ = [
+    "MANAGED_END_DIRECTIVE",
+    "MANAGED_START_DIRECTIVE",
+    "PROJECT_JSONC_NAME",
+    "TOOL_COMMENT_PREFIX",
+    "HostProjectShortcuts",
+    "ToolComment",
+    "dump_jsonc_document",
+    "has_env_value",
+    "iter_env_items",
+    "load_jsonc_file",
+    "normalize_jsonc_path",
+    "parse_tool_comment",
+    "read_env_bool",
+    "read_env_float",
+    "read_env_int",
+    "read_env_string",
+    "resolve_host_project_shortcuts",
+    "resolve_host_reload_dirs",
+    "resolve_project_dir",
+    "set_jsonc_path",
+]

pz_core/utils/env.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import os
+
+
+def _read_env_text(*names: str) -> str:
+    for name in names:
+        value = str(os.environ.get(name) or "").strip()
+        if value:
+            return value
+    return ""
+
+
+def read_env_string(default: str, *names: str) -> str:
+    value = _read_env_text(*names)
+    if value:
+        return value
+    return str(default)
+
+
+def read_env_int(default: int, *names: str) -> int:
+    value = _read_env_text(*names)
+    if value:
+        try:
+            return int(value)
+        except Exception:
+            return int(default)
+    return int(default)
+
+
+def read_env_bool(default: bool, *names: str) -> bool:
+    for name in names:
+        raw = os.environ.get(name)
+        if raw is None:
+            continue
+        return raw.strip().lower() in {"1", "true", "yes", "on"}
+    return bool(default)
+
+
+def read_env_float(default: float, *names: str) -> float:
+    value = _read_env_text(*names)
+    if value:
+        try:
+            return float(value)
+        except Exception:
+            return float(default)
+    return float(default)
+
+
+def has_env_value(*names: str) -> bool:
+    return bool(_read_env_text(*names))
+
+
+def iter_env_items() -> tuple[tuple[str, str], ...]:
+    return tuple((str(key), str(value)) for key, value in os.environ.items())
+
+
+__all__ = [
+    "has_env_value",
+    "iter_env_items",
+    "read_env_bool",
+    "read_env_float",
+    "read_env_int",
+    "read_env_string",
+]

pz_core/utils/project_jsonc/__init__.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from .document import (
+    MANAGED_END_DIRECTIVE,
+    MANAGED_START_DIRECTIVE,
+    PROJECT_JSONC_NAME,
+    TOOL_COMMENT_PREFIX,
+    ToolComment,
+    dump_jsonc_document,
+    load_jsonc_file,
+    load_jsonc_text,
+    normalize_jsonc_path,
+    parse_tool_comment,
+    set_jsonc_path,
+)
+
+__all__ = [
+    "MANAGED_END_DIRECTIVE",
+    "MANAGED_START_DIRECTIVE",
+    "PROJECT_JSONC_NAME",
+    "TOOL_COMMENT_PREFIX",
+    "ToolComment",
+    "dump_jsonc_document",
+    "load_jsonc_file",
+    "load_jsonc_text",
+    "normalize_jsonc_path",
+    "parse_tool_comment",
+    "set_jsonc_path",
+]