pz-cli 5.0.3__tar.gz → 5.0.4__tar.gz

{pz_cli-5.0.3 → pz_cli-5.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pz-cli
-Version: 5.0.3
+Version: 5.0.4
 Summary: PZ protocol compiler with bundled authoring and foundation implementations
 Project-URL: Homepage, https://github.com/JiXiangTools/pz
 Project-URL: Repository, https://github.com/JiXiangTools/pz

{pz_cli-5.0.3 → pz_cli-5.0.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pz-cli"
-version = "5.0.3"
+version = "5.0.4"
 description = "PZ protocol compiler with bundled authoring and foundation implementations"
 readme = "README.md"
 requires-python = ">=3.11"

{pz_cli-5.0.3 → pz_cli-5.0.4}/pz_contrib/pz_authoring/pz_authoring/checks/__init__.py

@@ -5,9 +5,15 @@ from .dev_sources import (
     build_dev_source_check_items,
     has_blocking_dev_source_failures,
 )
+from .url_authoring import (
+    build_url_authoring_check_items,
+    has_blocking_url_authoring_failures,
+)
 
 __all__ = [
     "BLOCKING_DEV_SOURCE_CODES",
     "build_dev_source_check_items",
+    "build_url_authoring_check_items",
     "has_blocking_dev_source_failures",
+    "has_blocking_url_authoring_failures",
 ]

{pz_cli-5.0.3 → pz_cli-5.0.4}/pz_contrib/pz_authoring/pz_authoring/checks/provider.py

@@ -14,6 +14,10 @@ from .dev_sources import (
     build_dev_source_check_items,
     has_blocking_dev_source_failures,
 )
+from .url_authoring import (
+    build_url_authoring_check_items,
+    has_blocking_url_authoring_failures,
+)
 
 
 class AuthoringCheckContributionProvider:
@@ -39,11 +43,17 @@ class AuthoringCheckContributionProvider:
             for conflict in identity_report.conflicts
         )
         source_items = build_dev_source_check_items(project_dir)
-        items = (*identity_items, *source_items)
+        url_items = build_url_authoring_check_items(
+            project_dir,
+            identity_report=identity_report,
+        )
+        items = (*identity_items, *source_items, *url_items)
         return CheckContribution(
             items=items,
             blocks_runtime_compile=(
-                bool(identity_items) or has_blocking_dev_source_failures(source_items)
+                bool(identity_items)
+                or has_blocking_dev_source_failures(source_items)
+                or has_blocking_url_authoring_failures(url_items)
             ),
         )
 

pz_cli-5.0.4/pz_contrib/pz_authoring/pz_authoring/checks/url_authoring.py

@@ -0,0 +1,314 @@
+from __future__ import annotations
+
+import ast
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from pz_core.assembly.diagnostics import CheckItem
+
+from ..source_identity import SourceIdentityReport, inspect_source_identities
+
+_OWNER = "pz_authoring.url_authoring"
+_EXPECTED_INCLUDE = "include(imported_module)"
+
+
+@dataclass(frozen=True, slots=True)
+class _UrlconfSource:
+    path: Path
+    scope: str
+
+
+def _iter_urlconf_sources(
+    project_dir: Path,
+    identity_report: SourceIdentityReport,
+) -> tuple[_UrlconfSource, ...]:
+    project_root = project_dir.expanduser().resolve(strict=False)
+    sources: list[_UrlconfSource] = []
+    project_urlconf = project_root / "urls.py"
+    if project_urlconf.is_file():
+        sources.append(_UrlconfSource(project_urlconf, "project:urls.py"))
+
+    seen = {project_urlconf.resolve(strict=False)}
+    for candidate in identity_report.candidates:
+        urlconf = candidate.package_root / "urls.py"
+        if not urlconf.is_file():
+            continue
+        resolved = urlconf.resolve(strict=False)
+        if resolved in seen:
+            continue
+        seen.add(resolved)
+        sources.append(
+            _UrlconfSource(
+                urlconf,
+                f"app:{candidate.app_id}:urls.py",
+            )
+        )
+    return tuple(sources)
+
+
+def _module_exists(path: Path) -> bool:
+    return path.with_suffix(".py").is_file() or (path / "__init__.py").is_file()
+
+
+def _resolve_imported_module(
+    source: _UrlconfSource,
+    node: ast.ImportFrom,
+    imported_name: str,
+    import_roots: tuple[Path, ...],
+) -> bool:
+    module_parts = tuple((node.module or "").split(".")) if node.module else ()
+    if node.level:
+        module_path = source.path.parent
+        for _index in range(node.level - 1):
+            module_path = module_path.parent
+        return _module_exists(
+            module_path.joinpath(*module_parts, imported_name)
+        )
+    relative_module = Path(*module_parts, imported_name)
+    return any(
+        _module_exists(import_root / relative_module)
+        for import_root in import_roots
+    )
+
+
+def _resolve_absolute_module(
+    module_name: str,
+    import_roots: tuple[Path, ...],
+) -> bool:
+    relative_module = Path(*module_name.split("."))
+    return any(
+        _module_exists(import_root / relative_module)
+        for import_root in import_roots
+    )
+
+
+def _imported_module_names(
+    source: _UrlconfSource,
+    tree: ast.Module,
+    *,
+    import_roots: tuple[Path, ...],
+) -> frozenset[str]:
+    imported: set[str] = set()
+    for node in tree.body:
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                if not _resolve_absolute_module(alias.name, import_roots):
+                    continue
+                imported.add(alias.asname or alias.name.split(".", maxsplit=1)[0])
+        elif isinstance(node, ast.ImportFrom):
+            for alias in node.names:
+                if alias.name == "*" or not _resolve_imported_module(
+                    source,
+                    node,
+                    alias.name,
+                    import_roots,
+                ):
+                    continue
+                imported.add(alias.asname or alias.name)
+    return frozenset(imported)
+
+
+def _package_import_root(package_root: Path) -> Path:
+    top_package = package_root
+    while (top_package.parent / "__init__.py").is_file():
+        top_package = top_package.parent
+    return top_package.parent
+
+
+def _static_import_roots(
+    project_dir: Path,
+    identity_report: SourceIdentityReport,
+) -> tuple[Path, ...]:
+    roots = {
+        project_dir.expanduser().resolve(strict=False),
+        *(
+            Path(entry or ".").expanduser().resolve(strict=False)
+            for entry in sys.path
+        ),
+    }
+    for candidate in identity_report.candidates:
+        roots.add(_package_import_root(candidate.package_root))
+        roots.add(candidate.distribution_root)
+        roots.add(candidate.distribution_root / "src")
+    return tuple(sorted((root for root in roots if root.is_dir()), key=str))
+
+
+def _include_call_names(tree: ast.Module) -> tuple[frozenset[str], frozenset[str]]:
+    direct_names = {"include"}
+    routing_module_names: set[str] = set()
+    for node in tree.body:
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                if alias.name != "pz_foundation.routing":
+                    continue
+                routing_module_names.add(alias.asname or "pz_foundation")
+        elif isinstance(node, ast.ImportFrom):
+            if node.module == "pz_foundation.routing":
+                direct_names.update(
+                    alias.asname or alias.name
+                    for alias in node.names
+                    if alias.name == "include"
+                )
+            elif node.module == "pz_foundation":
+                routing_module_names.update(
+                    alias.asname or alias.name
+                    for alias in node.names
+                    if alias.name == "routing"
+                )
+    return frozenset(direct_names), frozenset(routing_module_names)
+
+
+def _attribute_root_name(node: ast.Attribute) -> str | None:
+    value: ast.expr = node
+    while isinstance(value, ast.Attribute):
+        value = value.value
+    return value.id if isinstance(value, ast.Name) else None
+
+
+def _is_include_call(
+    call: ast.Call,
+    *,
+    direct_names: frozenset[str],
+    routing_module_names: frozenset[str],
+) -> bool:
+    if isinstance(call.func, ast.Name):
+        return call.func.id in direct_names
+    if not isinstance(call.func, ast.Attribute) or call.func.attr != "include":
+        return False
+    return _attribute_root_name(call.func) in routing_module_names
+
+
+def _include_target(call: ast.Call) -> ast.expr | None:
+    keyword_targets = [
+        keyword.value
+        for keyword in call.keywords
+        if keyword.arg == "urlconf_module"
+    ]
+    if len(call.args) == 1 and not keyword_targets:
+        return call.args[0]
+    if not call.args and len(keyword_targets) == 1:
+        return keyword_targets[0]
+    return None
+
+
+def _expression_kind(node: ast.expr | None) -> str:
+    if node is None:
+        return "missing or ambiguous urlconf argument"
+    if isinstance(node, ast.Constant) and isinstance(node.value, str):
+        return "string literal"
+    if isinstance(node, ast.Tuple):
+        return "tuple expression"
+    if isinstance(node, ast.Call):
+        return "call expression"
+    if isinstance(node, ast.Attribute):
+        return "attribute expression"
+    if isinstance(node, ast.Name):
+        return f"name {node.id!r} is not a statically resolved module import"
+    return f"{type(node).__name__} expression"
+
+
+def _invalid_include_item(
+    source: _UrlconfSource,
+    call: ast.Call,
+    target: ast.expr | None,
+) -> CheckItem:
+    return CheckItem(
+        severity="error",
+        code="PZ_CHECK_URL_INCLUDE_DECLARATION_INVALID",
+        owner=_OWNER,
+        scope=source.scope,
+        message="URLconf include() must receive a directly imported module object.",
+        ok=False,
+        expected=_EXPECTED_INCLUDE,
+        actual=f"{_expression_kind(target)} at line {call.lineno}",
+        repair_command=None,
+    )
+
+
+def _parse_error_item(
+    source: _UrlconfSource,
+    *,
+    actual: str,
+) -> CheckItem:
+    return CheckItem(
+        severity="error",
+        code="PZ_CHECK_URLCONF_PARSE_INVALID",
+        owner=_OWNER,
+        scope=source.scope,
+        message="Production URLconf must be readable, valid Python source.",
+        ok=False,
+        expected="valid Python URLconf",
+        actual=actual,
+        repair_command=None,
+    )
+
+
+def _check_urlconf(
+    source: _UrlconfSource,
+    *,
+    import_roots: tuple[Path, ...],
+) -> tuple[CheckItem, ...]:
+    try:
+        contents = source.path.read_text(encoding="utf-8")
+        tree = ast.parse(contents, filename=str(source.path))
+    except SyntaxError as exc:
+        return (
+            _parse_error_item(
+                source,
+                actual=f"syntax error at line {exc.lineno or 0}: {exc.msg}",
+            ),
+        )
+    except (OSError, UnicodeError):
+        return (_parse_error_item(source, actual="unreadable UTF-8 source"),)
+
+    imported_modules = _imported_module_names(
+        source,
+        tree,
+        import_roots=import_roots,
+    )
+    direct_names, routing_module_names = _include_call_names(tree)
+    items: list[CheckItem] = []
+    calls = sorted(
+        (node for node in ast.walk(tree) if isinstance(node, ast.Call)),
+        key=lambda node: (node.lineno, node.col_offset),
+    )
+    for call in calls:
+        if not _is_include_call(
+            call,
+            direct_names=direct_names,
+            routing_module_names=routing_module_names,
+        ):
+            continue
+        target = _include_target(call)
+        if isinstance(target, ast.Name) and target.id in imported_modules:
+            continue
+        items.append(_invalid_include_item(source, call, target))
+    return tuple(items)
+
+
+def build_url_authoring_check_items(
+    project_dir: Path,
+    *,
+    identity_report: SourceIdentityReport | None = None,
+) -> tuple[CheckItem, ...]:
+    report = (
+        identity_report
+        if identity_report is not None
+        else inspect_source_identities(project_dir, action="pz_check_urls")
+    )
+    import_roots = _static_import_roots(project_dir, report)
+    items: list[CheckItem] = []
+    for source in _iter_urlconf_sources(project_dir, report):
+        items.extend(_check_urlconf(source, import_roots=import_roots))
+    return tuple(items)
+
+
+def has_blocking_url_authoring_failures(items: tuple[CheckItem, ...]) -> bool:
+    return any(not item.ok for item in items)
+
+
+__all__ = [
+    "build_url_authoring_check_items",
+    "has_blocking_url_authoring_failures",
+]

pz_cli-5.0.4/pz_contrib/pz_authoring/pz_authoring/docs/README.md

@@ -0,0 +1,9 @@
+# pz_authoring
+
+`pz_authoring` 是 PZ 官方开发控制面最小子包，负责项目初始化、开发源码绑定、环境维护、脚手架与发布编排。
+
+它通过 `pz.root_cli` 接入根命令，通过 `pz.app_source_defaults` 向 core 的稳定编译协议提供官方默认 source 配置。core 不直接导入本包。
+
+它生成的 URL 脚手架遵守正式路由合同：项目根只有一个 `urls.py`；拥有 Web surface 的 app 只有一个 `<pkg>.urls`，无 Web surface 不生成空入口；简单路由直接使用 `path(路径字面或真实共享路径, 已导入 callable, ...)`，单次路径常量就地内联；只有真正复杂的子树才显式导入 URL 模块对象并 `include(module)`。Authoring、Preflight 与新脚手架都不生成或接受字符串 module path；Foundation 仅为旧生产 wheel 的滚动升级保留 deprecated runtime compatibility。普通路由不显式写 `name`，默认名由当前 `app_name` / namespace 与 `handler.__name__` 稳定推导；只有兼容既有反向名或同一 handler 多路由时才覆盖。路由构建与绑定仍由 `pz_foundation.routing` 唯一拥有。
+
+正式设计见 [设计文档.md](设计文档.md)。

{pz_cli-5.0.3 → pz_cli-5.0.4}/pz_contrib/pz_authoring/pz_authoring/docs//350/256/276/350/256/241/346/226/207/346/241/243.md

@@ -24,6 +24,17 @@
 - service 之间通过 typed request/result 与明确 owner 组合；CLI handler 只负责解析参数并调用 service，不直接拼 Git、文件事务或发布对象图。
 - 首次需要创建 `apps/.sources` 时，authoring 必须在任何 mkdir/clone 之前取得交互确认；非交互环境没有显式同意时失败，不能自行创建共享 source root。
 
+## URL 脚手架合同
+
+- Authoring 只生成声明源，不实现路由解析、绑定、反向生成、canonical 或 slash policy；这些处理唯一归属 `pz_foundation.routing`。
+- 项目脚手架只生成一个项目根 `urls.py`，`routing.root_urlconf` 指向它；不生成 `root_urls.py`、`url_paths.py` 或第二个项目 URL 聚合入口。根组合只消费 core 按正式 source-root / `apps.py` 规则发现的已声明 app，不按目录名、`pyproject.toml` 或 `urls.py` 猜 app；其中拥有 Web surface 的 app 显式导入 `urls` 模块对象再调用 `include(module)`，不把模块路径字符串藏在 `include()` 中，无 Web surface 的 app 不进入根组合。
+- 拥有 Web surface 的 app 只生成一个 `<pkg>/urls.py`；无 Web surface 的 app 不保留空 `urls.py` 或空 `routing/`。`urls.py` 只放路径与处理函数绑定，复杂声明与共享路径事实放在本 app 的 `routing/`。
+- 默认生成 FastAPI-first 的 `path(路径字面或共享路径, 直接 handler callable, ...)`；多级路由树先显式导入子 URL 模块对象，再使用 `include(module)`。`"module:function"` handler 字符串或 `include("module.path")` 字符串只属兼容边界，不能成为 app 脚手架默认。
+- 单次使用的路径字面就地写在 `path(...)` 中；只有共享 prefix、完整路径或客户端共用的路径事实进入 `routing/paths.py`。
+- 默认路由名由 `app_name` namespace 与 `handler.__name__` 形成；脚手架不为普通路由生成显式 `name`，它只服务兼容或歧义覆盖。
+- `mount()` 只用于必须隔离的独立 ASGI app；普通业务路由脚手架不生成 mount，也不生成 app-local `FastAPI` / `APIRouter` 旁路。
+- 项目根 `urls.py`、各级 `include()` 和 `urlpatterns` 的声明顺序就是 first-match 顺序；脚手架不暗示或生成“按路径具体度排序”的后处理。
+
 ## 接入
 
 - 根命令由 `pz.root_cli` entry point 分别注册，避免 core 内置 authoring 实现。

{pz_cli-5.0.3 → pz_cli-5.0.4}/pz_contrib/pz_authoring/pz_authoring/project_default.jsonc

@@ -60,7 +60,9 @@
     // Lock file name written under runtime_dir/locks for resource compilation.
     "lock_name": "resources.lock"
   },
-  "routing": {},
+  "routing": {
+    "root_urlconf": "urls"
+  },
   "events": {
     "declared": {}
   },

{pz_cli-5.0.3 → pz_cli-5.0.4}/pz_contrib/pz_authoring/pz_authoring/project_defaults.py

@@ -7,7 +7,7 @@ from pz_core.utils.project_jsonc import load_jsonc_file
 
 
 PROJECT_DEFAULT_JSONC_NAME = "project_default.jsonc"
-_MANAGED_ROOT_KEYS = frozenset({"installed_apps", "middlewares"})
+_MANAGED_ROOT_KEYS = frozenset({"installed_apps", "middlewares", "routing"})
 _OMIT = object()
 
 
@@ -34,6 +34,9 @@ def build_project_scaffold_payload(*, installed_apps: list[str] | None = None) -
         "project": {
             "static_version": 1,
         },
+        "routing": {
+            "root_urlconf": "urls",
+        },
     }
 
 

{pz_cli-5.0.3 → pz_cli-5.0.4}/pz_contrib/pz_authoring/pz_authoring/project_settings_service.py

@@ -449,7 +449,9 @@ def _build_settings_update_dry_run(
         )
     )
     selected_sources = _resolve_target_sources(target, discovered_sources)
-    compile_all_middlewares = compile_middlewares and target is None
+    compile_all_middlewares = compile_middlewares and (
+        target is None or reset_middlewares_order
+    )
     current_payload = _load_existing_document(config_path)
     next_payload = _build_updated_payload(
         project_dir,
@@ -1664,6 +1666,8 @@ def _managed_installed_app_entries(
 ) -> list[str]:
     seeded_entries = _seed_installed_app_entries(project_dir, current_payload, sources)
     if not preserve_existing:
+        if (project_dir / "apps").is_dir() and "apps" not in seeded_entries:
+            seeded_entries.append("apps")
         return _finalize_managed_installed_app_entries(project_dir, seeded_entries)
     existing = [
         item
@@ -1696,7 +1700,7 @@ def _finalize_managed_installed_app_entries(
 ) -> list[str]:
     finalized: list[str] = []
     seen: set[str] = set()
-    retain_apps = (project_dir / "apps").is_dir()
+    retain_apps = False
     for raw_entry in entries:
         entry = str(raw_entry).strip()
         if not entry or entry in seen:
@@ -1706,7 +1710,7 @@ def _finalize_managed_installed_app_entries(
             retain_apps = True
             continue
         finalized.append(entry)
-    if retain_apps:
+    if retain_apps and (project_dir / "apps").is_dir():
         finalized.append("apps")
     return finalized