ppx-py 6.0.0__py3-none-any.whl

ppx_py/__init__.py

@@ -0,0 +1,21 @@
+"""PPX V6 public runtime API."""
+
+from .application import Application
+from .bridge import Bridge, BridgeError, api_method
+from .settings import Settings, SettingsError
+from .runtime import create_application, run_project
+from .paths import app_data_path, resource_path
+
+__all__ = [
+    "Application",
+    "Bridge",
+    "BridgeError",
+    "Settings",
+    "SettingsError",
+    "api_method",
+    "app_data_path",
+    "create_application",
+    "resource_path",
+    "run_project",
+]
+__version__ = "6.0.0"

ppx_py/application.py

@@ -0,0 +1,95 @@
+"""PPX V6 application lifecycle."""
+
+from __future__ import annotations
+
+import mimetypes
+from pathlib import Path
+from typing import Any, Union
+
+from .bridge import Bridge, JavascriptAPI
+from .services import SystemService
+from .settings import Settings
+from .storage import JsonStorage
+from .update import ApplicationUpdater
+
+
+class Application:
+    def __init__(self, settings: Settings) -> None:
+        self.settings = settings
+        self.bridge = Bridge()
+        self.window: Any = None
+        self.storage = JsonStorage(settings.app_data_dir / settings.storage.filename)
+        self.system = SystemService(settings, lambda: self.window)
+        self.application_updater = ApplicationUpdater(
+            settings, lambda progress: self.bridge.emit("applicationUpdate.progress", progress)
+        )
+        self._register_core_api()
+
+    @classmethod
+    def from_config(cls, path: Union[str, Path] = "ppx.toml") -> "Application":
+        return cls(Settings.load(path))
+
+    def register_api(self, api: object) -> "Application":
+        self.bridge.register_api(api)
+        return self
+
+    def _register_core_api(self) -> None:
+        methods = {
+            "system.getAppInfo": self.system.get_app_info,
+            "system.getOwner": self.system.get_owner,
+            "system.openPath": self.system.open_path,
+            "system.openFileDialog": self.system.open_file_dialog,
+            "system.saveFileDialog": self.system.save_file_dialog,
+            "system.selectDirectory": self.system.select_directory,
+            "window.getState": self.system.get_window_state,
+            "window.minimize": self.system.minimize_window,
+            "window.maximize": self.system.maximize_window,
+            "window.restore": self.system.restore_window,
+            "window.toggleFullscreen": self.system.toggle_fullscreen,
+            "window.close": self.system.close_window,
+            "storage.get": self.storage.get,
+            "storage.set": self.storage.set,
+            "storage.delete": self.storage.delete,
+            "applicationUpdate.check": self.application_updater.check,
+            "applicationUpdate.download": self.application_updater.download,
+            "applicationUpdate.cancel": self.application_updater.cancel,
+        }
+        for name, handler in methods.items():
+            self.bridge.register(name, handler)
+
+    def run(self, *, dev: bool = False, cef: bool = False) -> None:
+        import webview
+
+        if dev:
+            url = f"http://127.0.0.1:{self.settings.development.port}/"
+        else:
+            url = str(self.settings.frontend_dir / "index.html")
+            if not Path(url).is_file():
+                raise FileNotFoundError(f"前端产物不存在，请先执行 ppx build: {url}")
+            mimetypes.add_type("application/javascript", ".js")
+
+        screen = webview.screens[0]
+        width = int(screen.width * self.settings.window.width_ratio)
+        height = int(screen.height * self.settings.window.height_ratio)
+        self.window = webview.create_window(
+            title=self.settings.project.name,
+            url=url,
+            js_api=JavascriptAPI(self.bridge),
+            width=width,
+            height=height,
+            min_size=(
+                int(width * self.settings.window.min_width_ratio),
+                int(height * self.settings.window.min_height_ratio),
+            ),
+            resizable=self.settings.window.resizable,
+            fullscreen=self.settings.window.fullscreen,
+            on_top=self.settings.window.always_on_top,
+            confirm_close=self.settings.window.confirm_close,
+            background_color=self.settings.window.background_color,
+        )
+        self.bridge.set_window(self.window)
+        self.window.events.shown += self._on_shown
+        webview.start(debug=dev, http_server=True, gui="cef" if cef else None)
+
+    def _on_shown(self, *_args: Any) -> None:
+        self.storage.initialize()

ppx_py/bridge.py

@@ -0,0 +1,147 @@
+"""A small, stable Python/JavaScript RPC boundary."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import json
+import logging
+import threading
+import uuid
+from collections.abc import Callable, Mapping, Sequence
+from typing import Any, Optional
+
+
+LOGGER = logging.getLogger(__name__)
+
+
+class BridgeError(Exception):
+    def __init__(self, code: str, message: str):
+        super().__init__(message)
+        self.code = code
+
+
+def api_method(name: str) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Explicitly expose a user method under a stable RPC name."""
+
+    if not name or "." not in name:
+        raise ValueError("PPX API 名称必须包含命名空间，例如 user.greet")
+
+    def decorate(function: Callable[..., Any]) -> Callable[..., Any]:
+        setattr(function, "__ppx_api_method__", name)
+        return function
+
+    return decorate
+
+
+class Bridge:
+    """The only object exposed to ``window.pywebview.api``."""
+
+    def __init__(self) -> None:
+        self._methods: dict[str, Callable[..., Any]] = {}
+        self._window: Any = None
+
+    def set_window(self, window: Any) -> None:
+        self._window = window
+
+    def register(self, name: str, handler: Callable[..., Any]) -> None:
+        if name in self._methods:
+            raise ValueError(f"PPX API 已注册: {name}")
+        self._methods[name] = handler
+
+    def register_api(self, api: object) -> None:
+        found = 0
+        for _, member in inspect.getmembers(api, predicate=callable):
+            name = getattr(member, "__ppx_api_method__", None)
+            if name:
+                self.register(name, member)
+                found += 1
+        if not found:
+            raise ValueError("业务 API 没有使用 @api_method 注册任何方法")
+
+    def call(self, method: str, params: Any = None, request_id: Optional[str] = None) -> dict[str, Any]:
+        request_id = request_id or uuid.uuid4().hex
+        try:
+            handler = self._methods.get(method)
+            if handler is None:
+                raise BridgeError("METHOD_NOT_FOUND", f"未注册的 API: {method}")
+            if params is None:
+                arguments, keywords = (), {}
+            elif isinstance(params, Mapping):
+                arguments, keywords = (), dict(params)
+            elif isinstance(params, Sequence) and not isinstance(params, (str, bytes, bytearray)):
+                arguments, keywords = tuple(params), {}
+            else:
+                raise BridgeError("INVALID_PARAMS", "params 必须是对象、数组或 null")
+            try:
+                inspect.signature(handler).bind(*arguments, **keywords)
+            except TypeError as exc:
+                raise BridgeError("INVALID_PARAMS", str(exc)) from exc
+            data = _resolve_awaitable(handler(*arguments, **keywords))
+            try:
+                json.dumps(data, allow_nan=False)
+            except (TypeError, ValueError) as exc:
+                raise BridgeError(
+                    "INVALID_RESULT", "Python API 返回值必须是可序列化的 JSON 数据"
+                ) from exc
+            return {"ok": True, "data": data, "error": None, "requestId": request_id}
+        except BridgeError as exc:
+            return self._failure(exc.code, str(exc), request_id)
+        except Exception:
+            LOGGER.exception("PPX Python API 执行失败: method=%s requestId=%s", method, request_id)
+            return self._failure("INTERNAL_ERROR", "Python API 执行失败", request_id)
+
+    def emit(self, event: str, data: Any) -> None:
+        if self._window is None:
+            return
+        # ASCII escaping also protects JavaScript parsing from U+2028/U+2029 separators.
+        event_json = json.dumps(event)
+        data_json = json.dumps(data, allow_nan=False)
+        self._window.evaluate_js(
+            f"if (typeof window.__ppxDispatch === 'function') window.__ppxDispatch({event_json}, {data_json})"
+        )
+
+    @staticmethod
+    def _failure(code: str, message: str, request_id: str) -> dict[str, Any]:
+        return {
+            "ok": False,
+            "data": None,
+            "error": {"code": code, "message": message},
+            "requestId": request_id,
+        }
+
+
+def _resolve_awaitable(value: Any) -> Any:
+    """Resolve async business methods behind pywebview's synchronous JS API."""
+    if not inspect.isawaitable(value):
+        return value
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        return asyncio.run(value)
+
+    result: list[Any] = []
+    failure: list[BaseException] = []
+
+    def run() -> None:
+        try:
+            result.append(asyncio.run(value))
+        except BaseException as exc:  # Re-raised on the calling thread below.
+            failure.append(exc)
+
+    worker = threading.Thread(target=run, name="ppx-async-api", daemon=True)
+    worker.start()
+    worker.join()
+    if failure:
+        raise failure[0]
+    return result[0]
+
+
+class JavascriptAPI:
+    """Only expose RPC dispatch; registration and event emission stay in Python."""
+
+    def __init__(self, bridge: Bridge) -> None:
+        self._bridge = bridge
+
+    def call(self, method: str, params: Any = None, request_id: Optional[str] = None) -> dict[str, Any]:
+        return self._bridge.call(method, params, request_id)

ppx_py/cli.py

@@ -0,0 +1,91 @@
+"""PPX command line entry point."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import List, Optional
+
+from . import __version__
+from .commands import build, dev, doctor, icon, update
+from .scaffold import create_project, initialize_project
+
+
+def _new(args: object) -> int:
+    try:
+        target = create_project(
+            str(getattr(args, "name")),
+            getattr(args, "directory", None),
+            str(getattr(args, "frontend", "vanilla")),
+        )
+        print(f"PPX 项目已创建: {target}")
+        print(f"下一步: cd {target.name} && ppx init && ppx dev")
+        return 0
+    except Exception as exc:
+        print(f"[失败] {exc}")
+        return 1
+
+
+def _init(_args: object) -> int:
+    return initialize_project()
+
+
+def make_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="ppx", description="PPX developer tools")
+    parser.add_argument("--version", action="version", version=f"PPX {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    new_parser = commands.add_parser("new", help="创建只有业务代码与可配置资源的新项目")
+    new_parser.add_argument("name", help="项目名称")
+    new_parser.add_argument("--directory", help="目标目录，默认使用项目名生成目录")
+    new_parser.add_argument(
+        "--frontend",
+        choices=("vanilla", "vue", "react"),
+        default="vanilla",
+        help="前端模板，默认 vanilla",
+    )
+    new_parser.set_defaults(handler=_new)
+
+    init_parser = commands.add_parser("init", help="安装业务依赖并检查项目")
+    init_parser.set_defaults(handler=_init)
+
+    doctor_parser = commands.add_parser("doctor", help="检查项目和开发环境")
+    doctor_parser.add_argument("--json", action="store_true", dest="json_output", help="输出机器可读 JSON")
+    doctor_parser.set_defaults(handler=doctor.run)
+
+    icon_parser = commands.add_parser("icon", help="从一张方形主图生成三端应用图标")
+    icon_parser.add_argument("source", help="至少 512×512 的方形 PNG/JPEG/WebP 图片")
+    icon_parser.add_argument("--output", help="输出目录，默认使用 ppx.toml 的 paths.assets")
+    icon_parser.set_defaults(handler=icon.run)
+
+    update_parser = commands.add_parser("update", help="安全更新 PPX 框架依赖")
+    mode = update_parser.add_mutually_exclusive_group()
+    mode.add_argument("--check", action="store_true", help="只检查可用更新")
+    mode.add_argument("--dry-run", action="store_true", help="显示更新计划，不修改文件或环境")
+    update_parser.add_argument("--to", metavar="VERSION", help="更新到指定 V6 版本")
+    update_parser.set_defaults(handler=update.run)
+
+    dev_parser = commands.add_parser("dev", help="同时启动前端与桌面窗口")
+    dev_parser.add_argument("--cef", action="store_true", help="使用 CEF（仅 Windows）")
+    dev_parser.add_argument("--skip-frontend", action="store_true", help="前端服务已启动时不重复启动")
+    dev_parser.set_defaults(handler=dev.run)
+
+    build_parser = commands.add_parser("build", help="构建前端并用 PyInstaller 打包")
+    build_parser.add_argument("--console", action="store_true", help="保留控制台窗口")
+    build_parser.add_argument("--skip-frontend", action="store_true", help="不重复构建前端")
+    build_parser.set_defaults(handler=build.run)
+    return parser
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    # Windows redirects stdout/stderr using the legacy system code page.
+    # CLI output is UTF-8 so Chinese diagnostics also work in pipes and logs.
+    for stream in (sys.stdout, sys.stderr):
+        if stream is not None and hasattr(stream, "reconfigure") and not stream.isatty():
+            stream.reconfigure(encoding="utf-8", errors="backslashreplace")
+    args = make_parser().parse_args(argv)
+    return int(args.handler(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ppx_py/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command implementations."""

ppx_py/commands/build.py

@@ -0,0 +1,47 @@
+"""Build the frontend and package the desktop application."""
+
+from __future__ import annotations
+
+import subprocess
+import shutil
+import sys
+
+from ..packaging import create_installer, create_spec
+from ..project import find_project_root, load_settings
+
+
+def run(args: object) -> int:
+    root = find_project_root()
+    settings = load_settings(root)
+    if not getattr(args, "skip_frontend", False):
+        result = subprocess.run(
+            [shutil.which("pnpm") or "pnpm", "-C", settings.paths.frontend, "run", "build"], cwd=root, check=False
+        )
+        if result.returncode:
+            return result.returncode
+    spec = create_spec(root, settings, bool(getattr(args, "console", False)))
+    command = [
+        sys.executable,
+        "-m",
+        "PyInstaller",
+        "--clean",
+        "--noconfirm",
+        "--distpath",
+        str(root / "build"),
+        "--workpath",
+        str(root / "build" / "cache" / "work"),
+        str(spec),
+    ]
+    result = subprocess.call(command, cwd=root)
+    if result:
+        return result
+    if getattr(args, "console", False):
+        print(f"调试应用已生成: {root / 'build'}")
+        return 0
+    try:
+        installer = create_installer(root, settings)
+        print(f"安装包已生成并验证: {installer}")
+        return 0
+    except Exception as exc:
+        print(f"[失败] {exc}")
+        return 1

ppx_py/commands/dev.py

@@ -0,0 +1,78 @@
+"""Run Vite and the PPX desktop runtime as one developer command."""
+
+from __future__ import annotations
+
+import subprocess
+import socket
+import time
+import os
+import signal
+import shutil
+
+from ..project import find_project_root, load_settings
+from ..runtime import run_project
+
+
+def _wait_for_port(port: int, process: subprocess.Popen[bytes], timeout: float = 30.0) -> None:
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if process.poll() is not None:
+            raise RuntimeError(f"前端开发服务提前退出，退出码 {process.returncode}")
+        try:
+            with socket.create_connection(("127.0.0.1", port), timeout=0.2):
+                return
+        except OSError:
+            time.sleep(0.1)
+    raise TimeoutError(f"等待前端开发服务端口 {port} 超时")
+
+
+def _stop(process: subprocess.Popen[bytes]) -> None:
+    if os.name == "nt":
+        if process.poll() is None:
+            subprocess.run(["taskkill", "/PID", str(process.pid), "/T", "/F"], capture_output=True, check=False)
+        return
+    try:
+        os.killpg(process.pid, signal.SIGTERM)
+    except ProcessLookupError:
+        return
+    try:
+        process.wait(timeout=5)
+    except subprocess.TimeoutExpired:
+        try:
+            os.killpg(process.pid, signal.SIGKILL)
+        except ProcessLookupError:
+            pass
+        process.wait()
+
+
+def run(args: object) -> int:
+    root = find_project_root()
+    settings = load_settings(root)
+    process = None
+    try:
+        if not getattr(args, "skip_frontend", False):
+            try:
+                with socket.create_connection(("127.0.0.1", settings.development.port), timeout=0.2):
+                    raise RuntimeError(
+                        f"端口 {settings.development.port} 已被占用。请修改 development.port；"
+                        "如果该端口是你已启动的当前项目前端，请使用 --skip-frontend。"
+                    )
+            except OSError:
+                pass
+            process = subprocess.Popen(
+                [shutil.which("pnpm") or "pnpm", "-C", settings.paths.frontend, "run", "dev",
+                 "--host", "127.0.0.1", "--port", str(settings.development.port), "--strictPort"],
+                cwd=root,
+                start_new_session=os.name != "nt",
+            )
+            _wait_for_port(settings.development.port, process)
+        run_project(root / "ppx.toml", dev=True, cef=bool(getattr(args, "cef", False)))
+        return 0
+    except KeyboardInterrupt:
+        return 130
+    except Exception as exc:
+        print(f"[失败] {exc}")
+        return 1
+    finally:
+        if process is not None:
+            _stop(process)

ppx_py/commands/doctor.py

@@ -0,0 +1,159 @@
+"""Validate a PPX V6 project and its current-platform toolchain."""
+
+from __future__ import annotations
+
+import importlib.metadata
+import json
+import platform
+import shutil
+import subprocess
+import sys
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import List, Optional
+
+from packaging.version import InvalidVersion, Version
+
+from ..project import find_project_root, load_settings, read_lock
+
+
+@dataclass
+class Check:
+    ok: bool
+    name: str
+    detail: str
+
+
+def _command_version(command: str, args: List[str]) -> Optional[str]:
+    executable = shutil.which(command)
+    if not executable:
+        return None
+    result = subprocess.run([executable, *args], capture_output=True, text=True, check=False)
+    value = (result.stdout or result.stderr).strip()
+    return value.splitlines()[0] if value else "unknown"
+
+
+def _at_least(value: Optional[str], required: str) -> bool:
+    if value is None:
+        return False
+    try:
+        return Version(value.lstrip("vV")) >= Version(required)
+    except InvalidVersion:
+        return False
+
+
+def _in_range(value: Optional[str], minimum: str, maximum_exclusive: str) -> bool:
+    if value is None:
+        return False
+    try:
+        parsed = Version(value.lstrip("vV"))
+        return Version(minimum) <= parsed < Version(maximum_exclusive)
+    except InvalidVersion:
+        return False
+
+
+def collect_checks(root: Path) -> List[Check]:
+    settings = load_settings(root)
+    checks = [
+        Check(settings.project.project_format == 6, "项目格式", f"V{settings.project.project_format}"),
+        Check(sys.version_info >= (3, 10), "Python", sys.version.split()[0]),
+    ]
+    node = _command_version("node", ["--version"])
+    pnpm = _command_version("pnpm", ["--version"])
+    checks.extend([
+        Check(_at_least(node, "22.13.0"), "Node.js", node or "未安装"),
+        Check(_in_range(pnpm, "11.0.0", "12.0.0"), "pnpm", pnpm or "未安装"),
+    ])
+    try:
+        installed = importlib.metadata.version("ppx-py")
+        checks.append(Check(installed == settings.framework.python, "ppx-py", f"已安装 {installed}，配置 {settings.framework.python}"))
+    except importlib.metadata.PackageNotFoundError:
+        checks.append(Check(False, "ppx-py", "未安装"))
+
+    js_manifest = settings.frontend_source_dir / "node_modules" / "ppx-js" / "package.json"
+    if js_manifest.is_file():
+        installed_js = str(json.loads(js_manifest.read_text(encoding="utf-8")).get("version", "未知"))
+        checks.append(Check(installed_js == settings.framework.javascript, "ppx-js", f"已安装 {installed_js}，配置 {settings.framework.javascript}"))
+    else:
+        checks.append(Check(False, "ppx-js", "未安装，请执行 ppx init"))
+
+    for name, target in (
+        ("api", root / "api"),
+        ("gui", settings.frontend_source_dir),
+        ("ppx/assets", settings.asset_dir),
+        ("api/requirements.txt", root / "api/requirements.txt"),
+    ):
+        checks.append(Check(target.exists(), name, "存在" if target.exists() else "缺失"))
+    for filename in ("logo.png", "logo.ico", "logo.icns", "dmg-background.png"):
+        target = settings.asset_dir / filename
+        checks.append(Check(target.is_file(), f"资源 {filename}", "存在" if target.is_file() else "缺失"))
+
+    try:
+        lock = read_lock(root)
+        framework = lock.get("framework", {})
+        compatibility = lock.get("compatibility", {})
+        lock_ok = (
+            lock.get("projectFormat") == 6
+            and framework.get("python") == settings.framework.python
+            and framework.get("javascript") == settings.framework.javascript
+            and compatibility.get("pythonApi") == settings.compatibility.python_api
+            and compatibility.get("javascriptApi") == settings.compatibility.javascript_api
+            and compatibility.get("dataSchema") == settings.compatibility.data_schema
+        )
+        checks.append(Check(lock_ok, "ppx.lock", "与 ppx.toml 一致" if lock_ok else "与 ppx.toml 不一致"))
+    except Exception as exc:
+        checks.append(Check(False, "ppx.lock", str(exc)))
+
+    system = platform.system()
+    if system == "Darwin":
+        checks.extend([
+            Check(shutil.which("hdiutil") is not None, "hdiutil", shutil.which("hdiutil") or "未安装"),
+            Check(_module_available("dmgbuild"), "dmgbuild", "已安装" if _module_available("dmgbuild") else "未安装"),
+        ])
+    elif system == "Windows":
+        from ..packaging.installer import _find_iscc
+        iscc = _find_iscc()
+        checks.append(Check(iscc is not None, "Inno Setup 6", str(iscc) if iscc else "未安装"))
+    elif system == "Linux":
+        checks.append(Check(shutil.which("dpkg-deb") is not None, "dpkg-deb", shutil.which("dpkg-deb") or "未安装"))
+    return checks
+
+
+def _module_available(name: str) -> bool:
+    try:
+        importlib.metadata.version(name)
+        return True
+    except importlib.metadata.PackageNotFoundError:
+        return False
+
+
+def run(args: object) -> int:
+    json_output = bool(getattr(args, "json_output", False))
+    try:
+        root = find_project_root()
+        checks = collect_checks(root)
+    except Exception as exc:
+        if json_output:
+            print(json.dumps({
+                "ok": False,
+                "project": str(locals().get("root", "")),
+                "summary": {"passed": 0, "failed": 1, "total": 1},
+                "checks": [asdict(Check(False, "项目", str(exc)))],
+            }, ensure_ascii=False, indent=2))
+            return 1
+        print(f"[失败] 项目: {exc}")
+        return 1
+    failed = sum(not item.ok for item in checks)
+    if json_output:
+        print(json.dumps({
+            "ok": failed == 0,
+            "project": str(root),
+            "summary": {"passed": len(checks) - failed, "failed": failed, "total": len(checks)},
+            "checks": [asdict(check) for check in checks],
+        }, ensure_ascii=False, indent=2))
+        return 1 if failed else 0
+    print(f"PPX Doctor: {root}")
+    for check in checks:
+        print(f"[{'通过' if check.ok else '失败'}] {check.name}: {check.detail}")
+    print(f"检查完成：{len(checks) - failed} 项通过，{failed} 项失败")
+    return 1 if failed else 0