yuanboot 0.1.5__py3-none-any.whl

yuanboot/__init__.py

@@ -0,0 +1,34 @@
+from yuanboot._version import __version__
+from yuanboot.configuration import Configuration, ConfigurationBuilder
+from yuanboot.dependency_injection import (
+    ServiceCollection,
+    ServiceLifetime,
+    ServiceProvider,
+    ServiceResolutionError,
+)
+from yuanboot.hosting import (
+    ApplicationEvent,
+    ApplicationLife,
+    BackgroundService,
+    Host,
+    HostBuilder,
+    HostedService,
+    HostEnvironment,
+)
+
+__all__ = [
+    "__version__",
+    "ApplicationEvent",
+    "ApplicationLife",
+    "BackgroundService",
+    "Configuration",
+    "ConfigurationBuilder",
+    "Host",
+    "HostBuilder",
+    "HostEnvironment",
+    "HostedService",
+    "ServiceCollection",
+    "ServiceLifetime",
+    "ServiceProvider",
+    "ServiceResolutionError",
+]

yuanboot/__main__.py

@@ -0,0 +1,3 @@
+from yuanboot.cli import main
+
+raise SystemExit(main())

yuanboot/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.5"

yuanboot/cli/__init__.py

@@ -0,0 +1,260 @@
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import os
+import signal
+import subprocess
+import sys
+import tomllib
+from contextlib import contextmanager
+from pathlib import Path
+
+from yuanboot import __version__
+from yuanboot.cli.scaffolding import FRAMEWORK_REPOSITORY, TEMPLATES, create_project
+from yuanboot.configuration import ConfigurationBuilder
+from yuanboot.environment import PROFILES
+from yuanboot.web.application import server_address
+
+
+def _run_process(command, **options):
+    """Forward container/process signals to the managed server before waiting for exit."""
+    if os.name == "posix":
+        # The CLI forwards terminal signals; isolating the child prevents duplicate SIGINTs.
+        options.setdefault("start_new_session", True)
+    with subprocess.Popen(command, **options) as process:
+        previous = {}
+        forwarded_signal = None
+
+        def forward(signum, frame):
+            nonlocal forwarded_signal
+            forwarded_signal = signum
+            if process.poll() is None:
+                process.send_signal(signum)
+
+        try:
+            for sig in (signal.SIGINT, signal.SIGTERM):
+                previous[sig] = signal.signal(sig, forward)
+            code = process.wait()
+            # Uvicorn re-raises a handled signal after its graceful shutdown.
+            if forwarded_signal is not None and code == -forwarded_signal:
+                return 0
+            return code if code >= 0 else 128 - code
+        finally:
+            for sig, handler in previous.items():
+                signal.signal(sig, handler)
+
+
+def _parser():
+    parser = argparse.ArgumentParser(
+        prog="yuanbootctl-python", description="yuanboot Python project tools"
+    )
+    parser.add_argument("--version", action="version", version=f"yuanbootctl-python {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True)
+    new = commands.add_parser("new", help="Create an application from a template")
+    new.add_argument("template", nargs="?")
+    new.add_argument("-l", "--list", "--templates", action="store_true", dest="list_templates")
+    new.add_argument("-n", "--name", "--projectName", default="demo")
+    new.add_argument("-p", "--path", default=".")
+    new.add_argument("--framework-repo", default=FRAMEWORK_REPOSITORY)
+    new.add_argument("--framework-ref", default="v" + __version__)
+    run = commands.add_parser("run", help="Run the current project's web or console host")
+    run.add_argument("-p", "--path", default=".")
+    run.add_argument("--profile", choices=PROFILES)
+    run.add_argument("--host")
+    run.add_argument("--port", type=int)
+    run.add_argument("--reload", action="store_true")
+    run.add_argument("--workers", type=int, default=1)
+    run.add_argument("--python", help="Use a Python environment with your project's dependencies")
+    build = commands.add_parser("build", help="Build wheel and sdist using python -m build")
+    build.add_argument("-p", "--path", default=".")
+    build.add_argument("--wheel", action="store_true")
+    build.add_argument("--sdist", action="store_true")
+    build.add_argument("--outdir")
+    build.add_argument("--python", help="Python interpreter with the build package installed")
+    commands.add_parser("version", help="Print framework version")
+    return parser
+
+
+def _run(args):
+    project = Path(args.path).expanduser().resolve()
+    with (project / "pyproject.toml").open("rb") as stream:
+        settings = tomllib.load(stream).get("tool", {}).get("yuanboot", {})
+    if not settings:
+        raise ValueError("Missing [tool.yuanboot] configuration in pyproject.toml")
+    env = os.environ.copy()
+    if args.profile:
+        env["YUANBOOT_PROFILE"] = args.profile
+    if args.port is not None:
+        env["YUANBOOT_PORT"] = str(args.port)
+    if settings.get("kind", "web") == "console":
+        if args.reload or args.workers != 1 or args.host or args.port is not None:
+            raise ValueError("Console projects do not support web server flags")
+        module = settings.get("module")
+        if not module:
+            raise ValueError("Console projects require tool.yuanboot.module")
+        command = [args.python or sys.executable, "-m", module]
+    else:
+        target = settings.get("app")
+        if not target:
+            raise ValueError("Web projects require tool.yuanboot.app")
+        if args.reload and args.workers != 1:
+            raise ValueError("--reload cannot be combined with multiple workers")
+        if args.workers < 1:
+            raise ValueError("--workers must be positive")
+        config = (
+            ConfigurationBuilder(project)
+            .add_yaml_file(optional=True)
+            .add_environment()
+            .add_flag_args(["--profile", args.profile] if args.profile else [])
+            .build()
+        )
+        host, port = server_address(config)
+        port = args.port if args.port is not None else port
+        if not 0 <= port <= 65535:
+            raise ValueError("Port must be between 0 and 65535")
+        command = [
+            args.python or sys.executable,
+            "-m",
+            "uvicorn",
+            target,
+            "--host",
+            args.host or host,
+            "--port",
+            str(port),
+            "--workers",
+            str(args.workers),
+        ]
+        if args.reload:
+            command.append("--reload")
+        if settings.get("factory"):
+            command.append("--factory")
+        tls = config.get_section("yuanboot.application.server.tls")
+        for key, flag in (("cert", "--ssl-certfile"), ("key", "--ssl-keyfile")):
+            if tls.get_string(key):
+                command.extend([flag, tls.get_string(key)])
+    if getattr(sys, "frozen", False) and not args.python:
+        return _run_embedded(command[2:], project, env)
+    with _external_runtime():
+        return _run_process(command, cwd=project, env=_external_environment(env))
+
+
+def _external_environment(env):
+    env = env.copy()
+    if getattr(sys, "frozen", False):
+        for key in ("LD_LIBRARY_PATH", "DYLD_LIBRARY_PATH"):
+            original = env.get(key + "_ORIG")
+            if original is None:
+                env.pop(key, None)
+            else:
+                env[key] = original
+    return env
+
+
+@contextmanager
+def _external_runtime():
+    """Keep bundled shared libraries out of an external Python interpreter's search path."""
+    frozen_windows = getattr(sys, "frozen", False) and sys.platform == "win32"
+    if frozen_windows:
+        import ctypes
+
+        ctypes.windll.kernel32.SetDllDirectoryW(None)
+    try:
+        yield
+    finally:
+        if frozen_windows:
+            ctypes.windll.kernel32.SetDllDirectoryW(sys._MEIPASS)
+
+
+def _run_embedded(arguments, project, env):
+    import runpy
+
+    previous_directory = Path.cwd()
+    previous_path, previous_argv = sys.path[:], sys.argv[:]
+    previous_environment = os.environ.copy()
+    previous_signals = {}
+    try:
+        os.chdir(project)
+        sys.path.insert(0, str(project))
+        os.environ.update(env)
+        # Uvicorn re-raises signals after shutdown; its outer CLI should exit successfully.
+        for sig in (signal.SIGINT, signal.SIGTERM):
+            previous_signals[sig] = signal.signal(sig, lambda signum, frame: None)
+        if arguments[0] == "uvicorn":
+            from uvicorn.main import main as uvicorn_main
+
+            uvicorn_main(
+                args=arguments[1:], prog_name="yuanbootctl-python run", standalone_mode=False
+            )
+        else:
+            sys.argv = [arguments[0]]
+            runpy.run_module(arguments[0], run_name="__main__", alter_sys=True)
+        return 0
+    finally:
+        for sig, handler in previous_signals.items():
+            signal.signal(sig, handler)
+        os.chdir(previous_directory)
+        sys.path[:] = previous_path
+        sys.argv[:] = previous_argv
+        os.environ.clear()
+        os.environ.update(previous_environment)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _parser()
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "new":
+            if args.list_templates:
+                for template in TEMPLATES.values():
+                    print(f"{template.name:14} {template.description}")
+            else:
+                if not args.template:
+                    parser.error("new requires TEMPLATE or --list")
+                destination = create_project(
+                    args.template,
+                    args.name,
+                    args.path,
+                    framework_repo=args.framework_repo,
+                    framework_ref=args.framework_ref,
+                )
+                print(f"Created {args.template}: {destination}")
+                print(f'cd "{destination}"')
+                if not getattr(sys, "frozen", False):
+                    print('python -m pip install -e ".[dev]"')
+                print("yuanbootctl-python run")
+        elif args.command == "run":
+            return _run(args)
+        elif args.command == "build":
+            executable = args.python
+            if getattr(sys, "frozen", False) and not executable:
+                suffix = "Scripts/python.exe" if os.name == "nt" else "bin/python"
+                candidate = Path(args.path).expanduser().resolve() / ".venv" / suffix
+                if not candidate.is_file():
+                    raise ValueError(
+                        "build requires a Python environment: "
+                        "install build, then use --python /path/to/python"
+                    )
+                executable = str(candidate)
+            if not executable and importlib.util.find_spec("build") is None:
+                raise ValueError('Install the build tool first: python -m pip install "build>=1.2"')
+            command = [executable or sys.executable, "-m", "build"]
+            for option in ("wheel", "sdist"):
+                if getattr(args, option):
+                    command.append("--" + option)
+            if args.outdir:
+                command.extend(["--outdir", args.outdir])
+            with _external_runtime():
+                return _run_process(
+                    command,
+                    cwd=Path(args.path).expanduser(),
+                    env=_external_environment(os.environ),
+                )
+        else:
+            print(f"yuanbootctl-python {__version__}")
+        return 0
+    except (OSError, ValueError) as exc:
+        print(f"yuanbootctl-python: {exc}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        return 130

yuanboot/cli/__main__.py

@@ -0,0 +1,3 @@
+from yuanboot.cli import main
+
+raise SystemExit(main())

yuanboot/cli/entrypoint.py

@@ -0,0 +1,9 @@
+"""Entry point for the standalone executable, including multiprocessing workers."""
+
+import multiprocessing
+
+from yuanboot.cli import main
+
+if __name__ == "__main__":
+    multiprocessing.freeze_support()
+    raise SystemExit(main())

yuanboot/cli/scaffolding.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+import json
+import keyword
+import re
+import shutil
+from dataclasses import dataclass
+from importlib.resources import files
+from pathlib import Path
+
+from yuanboot import __version__
+
+
+@dataclass(frozen=True)
+class ProjectTemplate:
+    name: str
+    description: str
+    layers: tuple[str, ...]
+
+
+TEMPLATES = {
+    item.name: item
+    for item in (
+        ProjectTemplate(
+            "webapi", "FastAPI endpoints, DI, validation and actuator", ("web", "webapi")
+        ),
+        ProjectTemplate("simpleweb", "Minimal HTTP application", ("web", "simpleweb")),
+        ProjectTemplate("mvc", "Controllers, services and Jinja2 views", ("web", "mvc")),
+        ProjectTemplate(
+            "microservice",
+            "Web API with a managed background worker",
+            ("web", "webapi", "microservice"),
+        ),
+        ProjectTemplate("console", "Console host with managed background services", ("console",)),
+        ProjectTemplate("grpc", "gRPC service with protobuf and managed host lifecycle", ("grpc",)),
+    )
+}
+
+FRAMEWORK_REPOSITORY = "https://github.com/liangboceo/yuanboot-python.git"
+
+
+def framework_requirement(*, repository=FRAMEWORK_REPOSITORY, ref=None, extras=""):
+    if repository.startswith("git@"):
+        repository = "ssh://" + repository.replace(":", "/", 1)
+    repository = repository.removeprefix("git+")
+    if not re.fullmatch(r"(?:ssh|https)://[A-Za-z0-9@._:/-]+", repository):
+        raise ValueError("Framework repository must be a Git SSH/HTTPS URL")
+    ref = ref or "v" + __version__
+    if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._/-]*", ref) or ".." in ref:
+        raise ValueError("Invalid framework Git ref")
+    name = f"yuanboot[{extras}]" if extras else "yuanboot"
+    return f"{name} @ git+{repository}@{ref}"
+
+
+def _walk(resource, prefix=Path()):
+    for child in sorted(resource.iterdir(), key=lambda p: p.name):
+        path = prefix / child.name
+        if child.is_dir():
+            yield from _walk(child, path)
+        elif child.name.endswith(".tpl"):
+            yield path.with_suffix(""), child.read_text(encoding="utf-8")
+
+
+def create_project(
+    template: str,
+    name: str = "demo",
+    path: str | Path = ".",
+    *,
+    framework_repo: str = FRAMEWORK_REPOSITORY,
+    framework_ref: str | None = None,
+) -> Path:
+    if template not in TEMPLATES:
+        raise ValueError(f"Unknown template {template!r}. Use 'yuanbootctl-python new --list'.")
+    if not re.fullmatch(r"[A-Za-z][A-Za-z0-9_-]{0,63}", name):
+        raise ValueError(
+            "Project name must start with a letter and contain letters, digits, '-' or '_'"
+        )
+    package = name.lower().replace("-", "_")
+    if keyword.iskeyword(package) or package == "yuanboot":
+        raise ValueError(f"Project name {name!r} conflicts with a Python keyword or the framework")
+    rendered = {}
+    root = files("yuanboot.cli").joinpath("templates")
+    substitutions = {
+        "__PROJECT__": name,
+        "__PACKAGE__": package,
+        "__TEMPLATE__": template,
+        "__YUANBOOT_VERSION__": __version__,
+        "__FRAMEWORK_REF__": framework_ref or "v" + __version__,
+        "__KIND__": "console" if template in {"console", "grpc"} else "web",
+        "__YUANBOOT_REQUIREMENT__": json.dumps(
+            framework_requirement(
+                repository=framework_repo,
+                ref=framework_ref,
+                extras="grpc" if template == "grpc" else "",
+            )
+        ),
+        "__YUANBOOT_COMPONENTS_REQUIREMENT__": json.dumps(
+            framework_requirement(repository=framework_repo, ref=framework_ref, extras="all")
+        ),
+    }
+    for layer in ("common", *TEMPLATES[template].layers):
+        for relative, content in _walk(root.joinpath(layer)):
+            target = str(relative).replace("__PACKAGE__", package)
+            for token, value in substitutions.items():
+                content = content.replace(token, value)
+            rendered[target] = content
+    destination = Path(path).expanduser().resolve() / name
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    # Exclusive creation also rejects existing empty directories and symlinks.
+    destination.mkdir(exist_ok=False)
+    try:
+        for relative, content in rendered.items():
+            target = destination / relative
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text(content, encoding="utf-8")
+    except BaseException:
+        shutil.rmtree(destination)
+        raise
+    return destination

yuanboot/cli/templates/common/.dockerignore.tpl

@@ -0,0 +1,7 @@
+.venv
+.git
+__pycache__
+.pytest_cache
+dist
+build
+.env

yuanboot/cli/templates/common/.gitignore.tpl

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+dist/
+build/
+.env

yuanboot/cli/templates/common/Dockerfile.tpl

@@ -0,0 +1,10 @@
+FROM python:3.12-slim
+RUN apt-get update && apt-get install -y --no-install-recommends git \
+    && rm -rf /var/lib/apt/lists/*
+WORKDIR /app
+COPY . .
+RUN pip install --no-cache-dir . && useradd --create-home appuser
+USER appuser
+ENV YUANBOOT_PROFILE=pro
+EXPOSE 8080
+CMD ["yuanbootctl-python", "run"]

yuanboot/cli/templates/common/README.md.tpl

@@ -0,0 +1,59 @@
+# __PROJECT__
+
+基于 **yuanboot-python** 的 __TEMPLATE__ 项目，Python 3.11+。
+
+## 项目文档
+
+| 文档 | 内容 |
+| --- | --- |
+| [yuanboot-python](spec/yuanboot-python.md) | 框架使用说明、配置、依赖注入、MVC 和生命周期 |
+| [核心组件](spec/components.md) | MySQL、Redis、Nacos、日志、服务发现与任务配置 |
+| [后端模块开发规范](spec/backend-module-development.md) | 业务分层、DTO、路由、事务和接口约定 |
+
+生成工具版本：`__YUANBOOT_VERSION__`；框架依赖引用：`__FRAMEWORK_REF__`。
+文档随项目生成，可离线查阅；后续业务规范可在 `spec` 中补充。
+
+## 快速启动
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[dev]"
+yuanbootctl-python run
+```
+
+框架通过 `pyproject.toml` 中的 Git tag 依赖安装，无需 PyPI。
+项目的版本和框架版本各自维护。升级框架时修改 Git tag 并更新依赖 lock。
+也可将框架依赖改为公开 PyPI 的 `yuanboot==<version>`，组件依赖使用 `yuanboot[all]==<version>`；
+gRPC 项目的基础依赖使用 `yuanboot[grpc]==<version>`，版本应与需要的框架版本一致。
+私有仓库需要配置 Git SSH/HTTPS 访问权限；默认 Dockerfile 适用于公开 HTTPS 仓库。
+本地联调先安装完整框架 `pip install -e '/path/to/yuanboot_python[all]'`，
+再用 `pip install --no-deps -e .` 安装业务代码。
+
+也可用独立二进制直接运行默认模板：`/path/to/yuanbootctl-python run`。
+项目引入额外依赖后，使用 `run --python /path/to/.venv/bin/python` 指定业务环境。
+
+## 组件与构建
+
+启用全部基础组件：`python -m pip install -e '.[dev,components]'`。
+`main.py` 的 `use_components()` 自动读取 MySQL、Redis、Nacos 注册、日志等配置。
+配置 `yuanboot.cloud.nacos.data_id` 后，Web/Console 模板会加载 Nacos 配置并监视更新。
+
+```bash
+yuanbootctl-python build
+yuanbootctl-python run --profile pro
+```
+
+Web 模板：`http://127.0.0.1:8080/docs` 查看 API 文档，
+`/actuator/health/readiness` 查看就绪状态。
+Console 模板：运行后台任务，Ctrl+C 或 SIGTERM 优雅停止。
+gRPC 模板：监听 `yuanboot.grpc.address`，默认 127.0.0.1:9090。
+
+## 环境与配置
+
+配置按 config.yml → config_<profile>.yml → YUANBOOT_ 环境变量覆盖。
+环境固定为 dev / fat / uat / pro；模板包含对应的四份配置，默认 dev。
+例如 `YUANBOOT_PORT=9000`、`YUANBOOT_GREETING__MESSAGE=hello`。
+`yuanbootctl-python run --port 9000 --reload` 适用于 Web 开发；
+`yuanbootctl-python run --workers 2` 适用于 Web 多进程部署。
+每个 worker 都会运行自己的后台服务，需要任务唯一性时请使用外部协调机制。

yuanboot/cli/templates/common/config.yml.tpl

@@ -0,0 +1,11 @@
+yuanboot:
+  application:
+    name: __PROJECT__
+    server:
+      address: ":8080"
+  logging:
+    level: INFO
+    json: false
+    console: true
+greeting:
+  message: "Hello from __PROJECT__"

yuanboot/cli/templates/common/config_dev.yml.tpl

@@ -0,0 +1,3 @@
+# Loaded over config.yml when YUANBOOT_PROFILE=dev (the default).
+greeting:
+  message: "Hello from __PROJECT__ (development)"

yuanboot/cli/templates/common/config_fat.yml.tpl

@@ -0,0 +1,3 @@
+# Supply secrets through environment variables, never commit credentials.
+greeting:
+  message: "Hello from __PROJECT__"

yuanboot/cli/templates/common/config_pro.yml.tpl

@@ -0,0 +1,3 @@
+# Supply secrets through environment variables, never commit credentials.
+greeting:
+  message: "Hello from __PROJECT__"

yuanboot/cli/templates/common/config_uat.yml.tpl

@@ -0,0 +1,3 @@
+# Supply secrets through environment variables, never commit credentials.
+greeting:
+  message: "Hello from __PROJECT__"

yuanboot/cli/templates/common/docker-compose.yml.tpl

@@ -0,0 +1,9 @@
+services:
+  app:
+    build: .
+    ports:
+      - "8080:8080"
+    environment:
+      YUANBOOT_PROFILE: pro
+    init: true
+    stop_grace_period: 30s

yuanboot/cli/templates/common/pyproject.toml.tpl

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "__PROJECT__"
+version = "0.1.0"
+description = "An application built with yuanboot"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [__YUANBOOT_REQUIREMENT__]
+
+[project.optional-dependencies]
+dev = ["build>=1.2"]
+components = [__YUANBOOT_COMPONENTS_REQUIREMENT__]
+
+[tool.hatch.build.targets.wheel]
+packages = ["__PACKAGE__"]
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[tool.yuanboot]
+kind = "__KIND__"
+app = "__PACKAGE__.main:app"
+module = "__PACKAGE__.main"