tauri-runtime 0.1.0__py3-none-any.whl

tauri_runtime/channel.py

@@ -0,0 +1,79 @@
+"""`Channel`：命令执行期间由 Python 向前端 `Channel` 推送数据的流。"""
+
+from __future__ import annotations
+
+from typing import Generic, TypeVar
+
+from .protocol import ChannelClose, ChannelData, Writer, split_payload
+
+T = TypeVar("T")
+
+
+class Channel(Generic[T]):
+    """指向前端 `Channel` 的单向数据流。
+
+    在命令处理器中以 `Channel[T]` 注解参数即可注入，参数名与前端传入的 `Channel` 参数名
+    对应（camelCase 自动转为 snake_case，如 `onProgress` → `on_progress`）。通道仅在命令
+    返回前有效；命令结束后通道被标记为已关闭，再次发送会抛出 `RuntimeError`。
+
+    `T` 为载荷类型，可以是任意可被 pydantic 序列化为 JSON 的值，也可以是 `Raw` / `bytes`
+    （以二进制帧体发送）。
+
+    Attributes:
+        id: 前端 `Channel` 的 id。
+        closed: 通道是否已关闭。
+
+    Example:
+        ```python
+        @app.command
+        async def count(n: int, on_item: Channel[int]) -> int:
+            for i in range(n):
+                await on_item.send(i)
+            return n
+        ```
+    """
+
+    def __init__(self, channel_id: int, writer: Writer) -> None:
+        self.id = channel_id
+        self.closed = False
+        self._writer = writer
+
+    def send_sync(self, value: T) -> None:
+        """同步发送一条数据，线程安全，供同步（`def`）命令处理器使用。
+
+        Args:
+            value: 载荷。
+
+        Raises:
+            RuntimeError: 通道已关闭。
+            ValueError: 载荷无法编码为合法 JSON（如包含 `NaN` / `±Infinity`）。
+            FrameTooLarge: 编码后超过帧大小上限。
+        """
+        if self.closed:
+            raise RuntimeError(f"channel {self.id} is closed")
+        fields, body = split_payload(value)
+        self._writer.write(ChannelData(channel=self.id, **fields), body)
+
+    async def send(self, value: T) -> None:
+        """发送一条数据，供异步（`async def`）命令处理器使用。
+
+        Args:
+            value: 载荷。
+
+        Raises:
+            RuntimeError: 通道已关闭。
+            ValueError: 载荷无法编码为合法 JSON（如包含 `NaN` / `±Infinity`）。
+            FrameTooLarge: 编码后超过帧大小上限。
+        """
+        self.send_sync(value)
+
+    def close_sync(self) -> None:
+        """同步关闭通道并通知前端；重复调用无副作用。"""
+        if self.closed:
+            return
+        self.closed = True
+        self._writer.write(ChannelClose(channel=self.id))
+
+    async def close(self) -> None:
+        """异步关闭通道并通知前端；重复调用无副作用。"""
+        self.close_sync()

tauri_runtime/cli/__init__.py

@@ -0,0 +1,75 @@
+"""`tauri-runtime` 命令行入口。"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from .bundle import BuildError, build
+from .scaffold import MANAGERS, ScaffoldError, Source, create, init
+from .templates import FRONTEND_SNIPPET
+
+
+def add_source_options(parser: argparse.ArgumentParser) -> None:
+    group = parser.add_mutually_exclusive_group()
+    group.add_argument("--git", action="store_true", help="install the plugin from GitHub instead of the registries")
+    group.add_argument("--path", type=Path, metavar="REPO", help="install the plugin from a local checkout")
+
+
+def source_of(options: argparse.Namespace) -> Source:
+    if options.path is not None:
+        return Source("path", options.path.resolve())
+    return Source("git") if options.git else Source()
+
+
+def report(project: Path, hints: list[str]) -> None:
+    """打印手动步骤与前端调用示例。"""
+    for hint in hints:
+        print(f"tauri-runtime: manual step: {hint}", file=sys.stderr)
+    print(f"tauri-runtime: Python backend ready in {project / 'src-python'}")
+    print(f"call it from the frontend:\n\n{FRONTEND_SNIPPET}")
+
+
+def parser() -> argparse.ArgumentParser:
+    root = argparse.ArgumentParser(prog="tauri-runtime")
+    commands = root.add_subparsers(dest="command", required=True)
+
+    build_parser = commands.add_parser("build", help="package the Python backend with Nuitka (standalone)")
+    build_parser.add_argument("--project", type=Path, default=Path.cwd(), help="Python project directory")
+
+    init_parser = commands.add_parser("init", help="add a Python backend (src-python) to an existing Tauri project")
+    init_parser.add_argument("--project", type=Path, default=Path.cwd(), help="Tauri project root")
+    init_parser.add_argument("--force", action="store_true", help="continue when src-python already exists")
+    add_source_options(init_parser)
+
+    create_parser = commands.add_parser("create", help="create a Tauri project with a Python backend")
+    create_parser.add_argument("name", help="project directory name")
+    create_parser.add_argument("--template", default="vue-ts", help="create-tauri-app template")
+    create_parser.add_argument("--manager", default="pnpm", choices=MANAGERS, help="frontend package manager")
+    add_source_options(create_parser)
+    return root
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """命令行入口：`tauri-runtime {build,init,create} ...`；`build` 的 `--` 之后的参数传给 Nuitka。"""
+    args = list(sys.argv[1:] if argv is None else argv)
+    extra: list[str] = []
+    if "--" in args:
+        index = args.index("--")
+        args, extra = args[:index], args[index + 1 :]
+    options = parser().parse_args(args)
+    try:
+        if options.command == "build":
+            print(f"tauri-runtime: built {build(options.project.resolve(), extra)}")
+        elif options.command == "init":
+            project = options.project.resolve()
+            report(project, init(project, source_of(options), force=options.force))
+        else:
+            project, hints = create(options.name, options.template, options.manager, source_of(options))
+            report(project, hints)
+    except (BuildError, ScaffoldError) as e:
+        print(f"tauri-runtime: {e}", file=sys.stderr)
+        return 1
+    return 0

tauri_runtime/cli/bundle.py

@@ -0,0 +1,127 @@
+"""`tauri-runtime build`：用 Nuitka 将 Python 后端打包为 standalone 目录。
+
+配置读取项目 `pyproject.toml` 的 `[tool.tauri-runtime.build]`，产物布局固定为
+`<output>/<name>/<name>`（Windows 为 `<name>.exe`），与 Rust 插件的 `Builder::bundle(name)` 对应。
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import tomllib
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+NAME_PATTERN = re.compile(r"^[A-Za-z0-9._-]+$")
+KEYS = frozenset({"entry", "name", "output", "nuitka-args"})
+
+
+class BuildError(Exception):
+    """打包失败（配置错误、缺少 Nuitka 或编译失败），消息直接展示给用户。"""
+
+
+@dataclass(frozen=True)
+class BuildConfig:
+    """`[tool.tauri-runtime.build]` 配置。
+
+    Attributes:
+        entry: 入口脚本，相对项目目录。
+        name: 可执行文件名与产物目录名，只能包含字母、数字、`.`、`_`、`-`。
+        output: 输出目录，相对项目目录。
+        nuitka_args: 透传给 Nuitka 的额外参数。
+    """
+
+    entry: str = "main.py"
+    name: str = "py-backend"
+    output: str = "dist"
+    nuitka_args: tuple[str, ...] = ()
+
+
+def load_config(project: Path) -> BuildConfig:
+    """读取项目的打包配置；缺少配置段时使用默认值，未知键或非法值抛出 `BuildError`。"""
+    pyproject = project / "pyproject.toml"
+    if not pyproject.is_file():
+        raise BuildError(f"{pyproject} not found; run inside your Python project or pass --project")
+    with pyproject.open("rb") as f:
+        data: dict[str, Any] = tomllib.load(f)
+    table: dict[str, Any] = data.get("tool", {}).get("tauri-runtime", {}).get("build", {})
+    unknown = set(table) - KEYS
+    if unknown:
+        raise BuildError(f"unknown keys in [tool.tauri-runtime.build]: {', '.join(sorted(unknown))}")
+    config = BuildConfig(
+        entry=str(table.get("entry", BuildConfig.entry)),
+        name=str(table.get("name", BuildConfig.name)),
+        output=str(table.get("output", BuildConfig.output)),
+        nuitka_args=tuple(str(a) for a in table.get("nuitka-args", ())),
+    )
+    if not NAME_PATTERN.match(config.name):
+        raise BuildError(f"invalid name '{config.name}': use letters, digits, '.', '_' or '-'")
+    return config
+
+
+def executable_name(name: str, platform: str = sys.platform) -> str:
+    """产物中可执行文件的文件名：Windows 追加 `.exe`。"""
+    return f"{name}.exe" if platform == "win32" else name
+
+
+def nuitka_available() -> bool:
+    """当前环境能否导入 Nuitka。"""
+    return importlib.util.find_spec("nuitka") is not None
+
+
+def nuitka_command(config: BuildConfig, build_dir: Path, extra: Sequence[str]) -> list[str]:
+    """构造 Nuitka standalone 编译命令；使用当前解释器，因此项目依赖均可被收集。"""
+    return [
+        sys.executable,
+        "-m",
+        "nuitka",
+        "--standalone",
+        "--assume-yes-for-downloads",
+        "--remove-output",
+        f"--output-dir={build_dir}",
+        f"--output-filename={config.name}",
+        *config.nuitka_args,
+        *extra,
+        config.entry,
+    ]
+
+
+def build(
+    project: Path,
+    extra: Sequence[str] = (),
+    run: Callable[..., subprocess.CompletedProcess[Any]] = subprocess.run,
+) -> Path:
+    """编译项目并将产物整理到 `<output>/<name>`，返回可执行文件路径。
+
+    在临时目录中编译，成功后才替换旧产物，失败时不会留下半成品。
+
+    Args:
+        project: Python 项目目录（包含 `pyproject.toml`）。
+        extra: 追加给 Nuitka 的命令行参数。
+        run: 执行子进程的函数，测试时可替换。
+
+    Raises:
+        BuildError: 配置错误、缺少 Nuitka 或入口脚本，或 Nuitka 以非零退出码结束。
+    """
+    config = load_config(project)
+    if not nuitka_available():
+        raise BuildError("Nuitka is not installed in this environment; run `uv add --dev nuitka`")
+    if not (project / config.entry).is_file():
+        raise BuildError(f"entry script {project / config.entry} not found")
+    target = project / config.output / config.name
+    with tempfile.TemporaryDirectory(prefix="tauri-runtime-build-") as tmp:
+        build_dir = Path(tmp)
+        result = run(nuitka_command(config, build_dir, extra), cwd=project, check=False)
+        if result.returncode != 0:
+            raise BuildError(f"nuitka failed with exit code {result.returncode}")
+        if target.exists():
+            shutil.rmtree(target)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        shutil.move(str(build_dir / f"{Path(config.entry).stem}.dist"), str(target))
+    return target / executable_name(config.name)

tauri_runtime/cli/scaffold.py

@@ -0,0 +1,310 @@
+"""`tauri-runtime init` / `create`：为 Tauri 项目接入 Python 后端。
+
+文件修改均为纯函数（输入文本 → 输出文本），可重复执行；外部命令经可替换的 `run` 执行。
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal
+
+from ..protocol import SDK_VERSION
+from .templates import (
+    BUNDLE_DIR,
+    BUNDLE_NAME,
+    GITIGNORE,
+    MAIN_PY,
+    REPO_URL,
+    build_rs_snippet,
+    pyproject_toml,
+    rust_snippet,
+)
+
+Runner = Callable[..., Any]
+
+CRATE = "tauri-plugin-py-runtime"
+NPM_PACKAGE = "tauri-plugin-py-runtime-api"
+GITHUB_SPEC = "github:InfernalAzazel/tauri-plugin-py-runtime"
+BUILD_STEP = "cd src-python && uv run tauri-runtime build"
+RESOURCE_SRC = f"{BUNDLE_DIR}/"
+RESOURCE_DST = f"{BUNDLE_NAME}/"
+PERMISSION = "py-runtime:default"
+BUILDER_CALL = "tauri::Builder::default()"
+BUILD_CALL = "tauri_build::build()"
+MANAGERS = ("pnpm", "yarn", "bun", "npm")
+LOCKFILES = (
+    ("pnpm-lock.yaml", "pnpm"),
+    ("yarn.lock", "yarn"),
+    ("bun.lock", "bun"),
+    ("bun.lockb", "bun"),
+    ("package-lock.json", "npm"),
+)
+
+
+class ScaffoldError(Exception):
+    """脚手架步骤失败（项目结构不符或外部命令出错）。"""
+
+
+@dataclass(frozen=True)
+class Source:
+    """插件三个包的来源：发布版本、GitHub 仓库或本地仓库目录（`path`）。"""
+
+    kind: Literal["registry", "git", "path"] = "registry"
+    path: Path | None = None
+
+
+def dump_json(data: object) -> str:
+    return json.dumps(data, indent=2, ensure_ascii=False) + "\n"
+
+
+def patch_tauri_conf(text: str) -> tuple[str, list[str]]:
+    """在 `beforeBuildCommand` 后追加 Nuitka 打包，并把产物加入 `bundle.resources`。
+
+    返回新文本与无法自动处理、需用户手动完成的提示。
+    """
+    conf = json.loads(text)
+    hints: list[str] = []
+
+    build = conf.setdefault("build", {})
+    command = build.get("beforeBuildCommand")
+    if not command:
+        build["beforeBuildCommand"] = BUILD_STEP
+    elif isinstance(command, str):
+        if BUILD_STEP not in command:
+            build["beforeBuildCommand"] = f"{command} && {BUILD_STEP}"
+    else:
+        hints.append(f'append "{BUILD_STEP}" to build.beforeBuildCommand')
+
+    bundle = conf.setdefault("bundle", {})
+    resources = bundle.get("resources")
+    if resources is None:
+        bundle["resources"] = {RESOURCE_SRC: RESOURCE_DST}
+    elif isinstance(resources, dict):
+        resources[RESOURCE_SRC] = RESOURCE_DST
+    else:
+        hints.append(f'add "{RESOURCE_SRC}" -> "{RESOURCE_DST}" to bundle.resources (map form)')
+
+    return dump_json(conf), hints
+
+
+def patch_capability(text: str) -> str:
+    """为 capability 文件的 `permissions` 加上插件默认权限。"""
+    conf = json.loads(text)
+    permissions = conf.setdefault("permissions", [])
+    if PERMISSION not in permissions:
+        permissions.append(PERMISSION)
+    return dump_json(conf)
+
+
+def patch_lib_rs(text: str) -> str | None:
+    """在唯一的 `tauri::Builder::default()` 行后插入插件注册。
+
+    已注册时原样返回；无法识别（没有或有多处该调用、调用不在行尾）时返回 None。
+    """
+    if "tauri_plugin_py_runtime" in text:
+        return text
+    if text.count(BUILDER_CALL) != 1:
+        return None
+    lines = text.splitlines(keepends=True)
+    for index, line in enumerate(lines):
+        if BUILDER_CALL in line:
+            if line.strip() != BUILDER_CALL:
+                return None
+            indent = line[: len(line) - len(line.lstrip())]
+            lines.insert(index + 1, rust_snippet(indent + "    "))
+            return "".join(lines)
+    return None
+
+
+def patch_build_rs(text: str) -> str | None:
+    """在唯一的 `tauri_build::build()` 前创建 Nuitka 产物目录。
+
+    tauri-build 在 dev / check 时也要求 `bundle.resources` 路径存在，而产物只在打包时生成。
+    已处理时原样返回；无法识别时返回 None。
+    """
+    if BUNDLE_DIR in text:
+        return text
+    if text.count(BUILD_CALL) != 1:
+        return None
+    lines = text.splitlines(keepends=True)
+    for index, line in enumerate(lines):
+        if BUILD_CALL in line:
+            if line.strip() != BUILD_CALL:
+                return None
+            lines.insert(index, build_rs_snippet(line[: len(line) - len(line.lstrip())]))
+            return "".join(lines)
+    return None
+
+
+def detect_package_manager(root: Path) -> str:
+    """依据锁文件判断前端包管理器；没有锁文件时看 `beforeDevCommand` 的首个单词，默认 npm。"""
+    for lockfile, manager in LOCKFILES:
+        if (root / lockfile).exists():
+            return manager
+    conf = root / "src-tauri" / "tauri.conf.json"
+    if conf.is_file():
+        command = json.loads(conf.read_text(encoding="utf-8")).get("build", {}).get("beforeDevCommand")
+        if isinstance(command, str) and command.split() and command.split()[0] in MANAGERS:
+            return command.split()[0]
+    return "npm"
+
+
+def cargo_add_command(source: Source) -> list[str]:
+    """在项目根目录执行的 `cargo add` 命令。"""
+    if source.kind == "git":
+        spec = [CRATE, "--git", REPO_URL]
+    elif source.kind == "path":
+        assert source.path is not None
+        spec = [CRATE, "--path", str(source.path)]
+    else:
+        spec = [f"{CRATE}@{SDK_VERSION}"]
+    return ["cargo", "add", *spec, "--manifest-path", str(Path("src-tauri") / "Cargo.toml")]
+
+
+def frontend_add_command(manager: str, source: Source) -> list[str]:
+    """安装前端 API 包的命令。"""
+    if source.kind == "git":
+        spec = GITHUB_SPEC
+    elif source.kind == "path":
+        assert source.path is not None
+        spec = f"{'link' if manager == 'pnpm' else 'file'}:{source.path}"
+    else:
+        spec = f"{NPM_PACKAGE}@{SDK_VERSION}"
+    if manager == "pnpm" and source.kind == "git":
+        # pnpm 10+ 默认禁止 git 依赖执行构建脚本（`prepare` 编译 dist-js），需显式放行。
+        return ["pnpm", "add", f"--allow-build={NPM_PACKAGE}", spec]
+    return [manager, "install" if manager == "npm" else "add", spec]
+
+
+def create_command(name: str, template: str, manager: str) -> list[str]:
+    """调用 create-tauri-app 创建项目的命令。"""
+    options = [name, "--template", template, "--manager", manager, "--yes"]
+    if manager == "npm":
+        return ["npm", "create", "tauri-app@latest", "--", *options]
+    return [manager, "create", "tauri-app", *options]
+
+
+def check_source(source: Source) -> None:
+    """本地来源须指向本仓库根目录（含 `python-sdk` 与 `Cargo.toml`）。"""
+    if source.kind != "path":
+        return
+    assert source.path is not None
+    if not ((source.path / "python-sdk").is_dir() and (source.path / "Cargo.toml").is_file()):
+        raise ScaffoldError(f"{source.path} is not a tauri-plugin-py-runtime checkout")
+
+
+def run_step(run: Runner, cmd: Sequence[str], cwd: Path) -> None:
+    """执行外部命令，失败时抛出 ScaffoldError；经 `shutil.which` 解析以支持 Windows 的 `.cmd`。"""
+    print(f"tauri-runtime: $ {' '.join(cmd)}", flush=True)
+    program = shutil.which(cmd[0])
+    if program is None:
+        raise ScaffoldError(f"`{cmd[0]}` not found on PATH")
+    result = run([program, *cmd[1:]], cwd=cwd, check=False)
+    if result.returncode != 0:
+        raise ScaffoldError(f"`{' '.join(cmd)}` failed with exit code {result.returncode}")
+
+
+def write_backend(directory: Path, source: Source) -> None:
+    """生成 `src-python`；已有文件保持不变。"""
+    directory.mkdir(parents=True, exist_ok=True)
+    files = {"pyproject.toml": pyproject_toml(source), "main.py": MAIN_PY, ".gitignore": GITIGNORE}
+    for name, content in files.items():
+        path = directory / name
+        if not path.exists():
+            path.write_text(content, encoding="utf-8")
+
+
+def patch_file(path: Path, patch: Callable[[str], str]) -> None:
+    text = path.read_text(encoding="utf-8")
+    patched = patch(text)
+    if patched != text:
+        path.write_text(patched, encoding="utf-8")
+
+
+def init(
+    project: Path,
+    source: Source | None = None,
+    force: bool = False,
+    manager: str | None = None,
+    run: Runner = subprocess.run,
+) -> list[str]:
+    """为已有 Tauri 项目接入 Python 后端，返回需用户手动完成的提示。"""
+    source = source or Source()
+    check_source(source)
+    tauri_dir = project / "src-tauri"
+    if not tauri_dir.is_dir():
+        raise ScaffoldError(f"{tauri_dir} not found; run inside a Tauri project or pass --project")
+    backend = project / "src-python"
+    if backend.exists() and not force:
+        raise ScaffoldError(f"{backend} already exists; pass --force to keep it and finish the setup")
+    hints: list[str] = []
+
+    write_backend(backend, source)
+    run_step(run, ["uv", "sync"], backend)
+
+    conf = tauri_dir / "tauri.conf.json"
+    if conf.is_file():
+        text, conf_hints = patch_tauri_conf(conf.read_text(encoding="utf-8"))
+        conf.write_text(text, encoding="utf-8")
+        hints += [f"tauri.conf.json: {hint}" for hint in conf_hints]
+    else:
+        hints.append(
+            f'Tauri config: append "{BUILD_STEP}" to build.beforeBuildCommand and map '
+            f'"{RESOURCE_SRC}" to "{RESOURCE_DST}" in bundle.resources'
+        )
+
+    capability = tauri_dir / "capabilities" / "default.json"
+    if capability.is_file():
+        patch_file(capability, patch_capability)
+    else:
+        hints.append(f'add "{PERMISSION}" to the permissions of your capability file')
+
+    run_step(run, cargo_add_command(source), project)
+
+    if (project / "package.json").is_file():
+        run_step(run, frontend_add_command(manager or detect_package_manager(project), source), project)
+        if source.kind == "path" and source.path is not None and not (source.path / "dist-js").is_dir():
+            hints.append(f"build the frontend package first: run `pnpm install && pnpm build` in {source.path}")
+    else:
+        hints.append(f"install the frontend package {NPM_PACKAGE}")
+
+    lib_rs = tauri_dir / "src" / "lib.rs"
+    patched = patch_lib_rs(lib_rs.read_text(encoding="utf-8")) if lib_rs.is_file() else None
+    if patched is None:
+        hints.append(f"register the plugin on your tauri::Builder:\n{rust_snippet('    ')}")
+    else:
+        patch_file(lib_rs, lambda _: patched)
+
+    build_rs = tauri_dir / "build.rs"
+    patched = patch_build_rs(build_rs.read_text(encoding="utf-8")) if build_rs.is_file() else None
+    if patched is None:
+        hints.append(f"create the Python bundle directory before tauri_build::build() in build.rs:\n{build_rs_snippet('    ')}")
+    else:
+        patch_file(build_rs, lambda _: patched)
+    return hints
+
+
+def create(
+    name: str,
+    template: str = "vue-ts",
+    manager: str = "pnpm",
+    source: Source | None = None,
+    cwd: Path | None = None,
+    run: Runner = subprocess.run,
+) -> tuple[Path, list[str]]:
+    """用 create-tauri-app 新建项目后执行 `init`，返回项目目录与提示。"""
+    source = source or Source()
+    check_source(source)
+    cwd = cwd or Path.cwd()
+    project = cwd / name
+    if project.exists():
+        raise ScaffoldError(f"{project} already exists")
+    run_step(run, create_command(name, template, manager), cwd)
+    if not project.is_dir():
+        raise ScaffoldError(f"create-tauri-app did not create {project}")
+    return project, init(project, source, manager=manager, run=run)

tauri_runtime/cli/templates.py

@@ -0,0 +1,92 @@
+"""`tauri-runtime init` 生成的文件模板与打印给用户的代码片段。"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .scaffold import Source
+
+REPO_URL = "https://github.com/InfernalAzazel/tauri-plugin-py-runtime"
+BUNDLE_NAME = "py-backend"
+BUNDLE_DIR = f"../src-python/dist/{BUNDLE_NAME}"
+
+MAIN_PY = '''\
+from tauri_runtime import App
+
+app = App()
+
+
+@app.command
+async def greet(name: str) -> str:
+    return f"Hello {name}, from Python!"
+
+
+app.run()
+'''
+
+GITIGNORE = """\
+.venv/
+dist/
+__pycache__/
+"""
+
+FRONTEND_SNIPPET = """\
+import { pyInvoke } from "tauri-plugin-py-runtime-api";
+
+const message = await pyInvoke<string>("greet", { name: "Tauri" });
+"""
+
+
+def rust_snippet(indent: str = "") -> str:
+    """注册插件的链式调用片段，每行加 `indent` 前缀。"""
+    lines = [
+        ".plugin(",
+        "    tauri_plugin_py_runtime::Builder::new()",
+        '        .script("../src-python/main.py")',
+        f'        .bundle("{BUNDLE_NAME}")',
+        "        .build(),",
+        ")",
+    ]
+    return "".join(f"{indent}{line}\n" for line in lines)
+
+
+def build_rs_snippet(indent: str = "") -> str:
+    """`build.rs` 中创建 Nuitka 产物目录的语句，供 tauri-build 校验 `bundle.resources`。"""
+    lines = [
+        "// tauri-build 要求 bundle.resources 的路径存在；Nuitka 产物由 `tauri-runtime build` 生成。",
+        f'std::fs::create_dir_all("{BUNDLE_DIR}").expect("failed to create the Python bundle directory");',
+    ]
+    return "".join(f"{indent}{line}\n" for line in lines)
+
+
+def uv_source(source: Source) -> str | None:
+    """`[tool.uv.sources]` 中 `tauri-runtime` 的取值；registry 来源无需此项。"""
+    if source.kind == "git":
+        return f'{{ git = "{REPO_URL}", subdirectory = "python-sdk" }}'
+    if source.kind == "path":
+        assert source.path is not None
+        return f"{{ path = {json.dumps((source.path / 'python-sdk').as_posix())}, editable = true }}"
+    return None
+
+
+def pyproject_toml(source: Source) -> str:
+    """`src-python/pyproject.toml`：依赖 SDK、dev 组含 Nuitka，打包名与 Rust `bundle` 对应。"""
+    text = """\
+[project]
+name = "backend"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = ["tauri-runtime"]
+
+[dependency-groups]
+dev = ["nuitka"]
+
+[tool.uv]
+package = false
+"""
+    value = uv_source(source)
+    if value is not None:
+        text += f"\n[tool.uv.sources]\ntauri-runtime = {value}\n"
+    return text + f'\n[tool.tauri-runtime.build]\nname = "{BUNDLE_NAME}"\n'