yuanboot 0.1.5__tar.gz

yuanboot-0.1.5/.gitignore

@@ -0,0 +1,15 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+.env
+.env.*
+!.env.example
+*.log
+.DS_Store
+.idea/
+.vscode/

yuanboot-0.1.5/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2019 max zhang
+Copyright (c) 2026 yuanboot contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

yuanboot-0.1.5/PKG-INFO

@@ -0,0 +1,257 @@
+Metadata-Version: 2.4
+Name: yuanboot
+Version: 0.1.5
+Summary: A dependency-injected Python microservice framework built on FastAPI
+Project-URL: Homepage, https://github.com/liangboceo/yuanboot-python
+Project-URL: Documentation, https://github.com/liangboceo/yuanboot-python/tree/master/docs
+Project-URL: Repository, https://github.com/liangboceo/yuanboot-python
+Project-URL: Issues, https://github.com/liangboceo/yuanboot-python/issues
+Project-URL: Releases, https://github.com/liangboceo/yuanboot-python/releases
+Author: yuanboot contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: dependency-injection,fastapi,microservice,nacos,yuanboot
+Classifier: Framework :: FastAPI
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.11
+Requires-Dist: fastapi<1,>=0.115
+Requires-Dist: jinja2<4,>=3.1
+Requires-Dist: prometheus-client<1,>=0.21
+Requires-Dist: pydantic<3,>=2.9
+Requires-Dist: pyyaml<7,>=6
+Requires-Dist: uvicorn[standard]<1,>=0.30
+Provides-Extra: all
+Requires-Dist: croniter<7,>=3; extra == 'all'
+Requires-Dist: grpcio-health-checking<2,>=1.66; extra == 'all'
+Requires-Dist: grpcio<2,>=1.66; extra == 'all'
+Requires-Dist: httpx<1,>=0.27; extra == 'all'
+Requires-Dist: pyjwt<3,>=2.9; extra == 'all'
+Requires-Dist: pymysql[rsa]<2,>=1.1; extra == 'all'
+Requires-Dist: redis<8,>=5; extra == 'all'
+Requires-Dist: sqlalchemy<3,>=2.0; extra == 'all'
+Provides-Extra: apollo
+Requires-Dist: httpx<1,>=0.27; extra == 'apollo'
+Provides-Extra: binary
+Requires-Dist: pyinstaller<7,>=6.16; extra == 'binary'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Requires-Dist: twine<7,>=6; extra == 'dev'
+Provides-Extra: discovery
+Requires-Dist: httpx<1,>=0.27; extra == 'discovery'
+Provides-Extra: grpc
+Requires-Dist: grpcio-health-checking<2,>=1.66; extra == 'grpc'
+Requires-Dist: grpcio<2,>=1.66; extra == 'grpc'
+Provides-Extra: http
+Requires-Dist: httpx<1,>=0.27; extra == 'http'
+Provides-Extra: jwt
+Requires-Dist: pyjwt<3,>=2.9; extra == 'jwt'
+Provides-Extra: mysql
+Requires-Dist: pymysql[rsa]<2,>=1.1; extra == 'mysql'
+Requires-Dist: sqlalchemy<3,>=2.0; extra == 'mysql'
+Provides-Extra: nacos
+Requires-Dist: httpx<1,>=0.27; extra == 'nacos'
+Provides-Extra: redis
+Requires-Dist: redis<8,>=5; extra == 'redis'
+Provides-Extra: scheduler
+Requires-Dist: croniter<7,>=3; extra == 'scheduler'
+Provides-Extra: xxljob
+Requires-Dist: httpx<1,>=0.27; extra == 'xxljob'
+Description-Content-Type: text/markdown
+
+# yuanboot-python
+
+简单、轻量、快速的 Python 微服务框架，基于 FastAPI、Uvicorn 和依赖注入构建，支持 Web API、MVC、gRPC 与后台服务。Python 3.11+。
+
+[![Build](https://github.com/liangboceo/yuanboot-python/actions/workflows/ci.yml/badge.svg)](https://github.com/liangboceo/yuanboot-python/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/v/tag/liangboceo/yuanboot-python?label=release&sort=semver)](https://github.com/liangboceo/yuanboot-python/releases)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
+[![License](https://img.shields.io/github/license/liangboceo/yuanboot-python)](LICENSE)
+
+## 框架特色
+
+- 路由分组、MVC 控制器、请求校验、OpenAPI 和 WebSocket。
+- Singleton、Scoped、Transient 依赖注入与资源自动释放。
+- 统一宿主、应用生命周期、后台服务和优雅退出。
+- YAML / JSON、多环境配置、环境变量和远程配置热更新。
+- MySQL、Redis、Nacos 配置中心、服务注册与发现。
+- 结构化日志、请求追踪、健康检查、Prometheus 和 JWT。
+- HTTP 客户端、定时任务、SMTP、gRPC 和 XXL-Job BEAN 执行器。
+- `yuanbootctl-python` 提供六类项目模板、运行和构建命令。
+
+## 下载命令行工具
+
+从 [GitHub Releases](https://github.com/liangboceo/yuanboot-python/releases) 下载对应系统和架构的压缩包，解压后即可执行，无需预装 Python。
+
+| 系统 | 架构 | 文件后缀 |
+| --- | --- | --- |
+| Linux | amd64 / arm64 | `_linux_amd64.tar.gz` / `_linux_arm64.tar.gz` |
+| macOS | Intel / Apple Silicon | `_darwin_amd64.tar.gz` / `_darwin_arm64.tar.gz` |
+| Windows | amd64 | `_windows_amd64.zip` |
+
+例如 Linux amd64：
+
+```bash
+VERSION=0.1.5
+curl -fLO "https://github.com/liangboceo/yuanboot-python/releases/download/v${VERSION}/yuanbootctl-python_${VERSION}_linux_amd64.tar.gz"
+tar -xzf "yuanbootctl-python_${VERSION}_linux_amd64.tar.gz"
+chmod +x yuanbootctl-python
+./yuanbootctl-python --version
+./yuanbootctl-python new webapi -n demo
+cd demo
+../yuanbootctl-python run --profile dev
+```
+
+访问 [API 文档](http://127.0.0.1:8080/docs)。Windows 使用 `yuanbootctl-python.exe`。
+Release 同时提供 `SHA256SUMS`、wheel 和源码包。
+
+独立可执行文件包含 Python 运行时、框架和标准组件，可以直接创建、运行模板项目。
+业务增加其他 Python 依赖后，可使用 `run --python /path/to/.venv/bin/python` 选择业务环境。
+`build` 打包 Python 项目，需要业务环境安装 `build`，详见 [命令行与发布说明](docs/releases.md)。
+
+## 安装框架
+
+从公开 PyPI 安装框架或项目工具：
+
+```bash
+python -m pip install 'yuanboot[all]==0.1.5'
+# 也可通过工具包安装同版本框架和命令：
+python -m pip install yuanbootctl-python==0.1.5
+yuanbootctl-python --version
+```
+
+`yuanbootctl-python` 自动依赖同版本的 `yuanboot`，命令入口和模板资源统一由框架提供。
+`yuanbootctl-python[all]` 会安装全部标准组件。PyPI 安装方式需要 Python 3.11+。
+
+业务项目也可使用 Git tag 固定框架版本：
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install 'yuanboot[all] @ git+https://github.com/liangboceo/yuanboot-python.git@v0.1.5'
+yuanbootctl-python new mvc -n orders
+cd orders
+python -m pip install -e '.[dev,components]'
+yuanbootctl-python run --reload
+```
+
+按需选择 `mysql`、`redis`、`nacos`、`grpc` 等 extras；`all` 安装全部标准组件。
+框架和业务项目分别管理版本，业务项目提交自己的依赖锁文件。
+生成的项目默认保持 Git tag 依赖；使用 PyPI 时可将依赖改为 `yuanboot==0.1.5`、
+`yuanboot[all]==0.1.5`（gRPC 项目使用 `yuanboot[grpc]==0.1.5`）。
+
+## 项目模板
+
+| 模板 | 内容 |
+| --- | --- |
+| `simpleweb` | 最小 HTTP 应用与运维端点 |
+| `webapi` | API 路由、服务注入和请求校验 |
+| `mvc` | 控制器、服务层和 Jinja2 页面 |
+| `microservice` | Web API、监控和后台服务 |
+| `console` | 命令行宿主与后台任务 |
+| `grpc` | gRPC 服务与健康检查 |
+
+模板包含项目元数据、配置、Dockerfile、Compose、README 和 `spec` 开发文档。
+每个新项目默认提供以下文档，可离线查阅：
+
+```text
+README.md
+spec/
+├── yuanboot-python.md             # 框架使用说明
+├── components.md                 # 核心组件配置与使用
+└── backend-module-development.md  # 后端模块开发规范
+```
+
+```bash
+yuanbootctl-python new --list
+yuanbootctl-python new mvc -n my-app
+yuanbootctl-python new grpc -n rpc-demo
+yuanbootctl-python run --profile fat --port 9000
+yuanbootctl-python run --workers 2
+yuanbootctl-python build
+yuanbootctl-python version
+```
+
+## 简单示例
+
+```python
+from yuanboot.web import create_default_builder
+from yuanboot.web.endpoints import use_actuator
+
+
+def endpoints(router):
+    use_actuator(router)
+
+    @router.get("/info")
+    def info():
+        return {"info": "ok"}
+
+
+host = create_default_builder(endpoints).build()
+app = host.app
+
+if __name__ == "__main__":
+    host.run()
+```
+
+默认监听 `0.0.0.0:8080`。可通过宿主构建器配置服务注册、中间件、路由和生命周期。
+
+## 环境与配置
+
+支持 `dev / fat / uat / pro`，默认 `dev`。通过 `--profile` 或 `YUANBOOT_PROFILE` 选择环境。
+
+```text
+config.yml
+config_dev.yml
+config_fat.yml
+config_uat.yml
+config_pro.yml
+```
+
+配置优先级：默认值 < 基础配置 < 环境配置 < 远程配置 < 环境变量 < 命令行。
+MySQL、Redis 和 Nacos 等组件按配置启用；Nacos 注册 metadata 的 `yuanboot_env` 使用当前环境名。
+
+```yaml
+yuanboot:
+  application:
+    name: orders
+    server:
+      address: ":8080"
+```
+
+支持 `${ENV:default}` 插值和 Pydantic 模型绑定，敏感信息通过环境变量提供。
+
+## 核心组件
+
+| 能力 | 组件 |
+| --- | --- |
+| 数据与缓存 | MySQL / SQLAlchemy、Redis |
+| 配置中心 | Nacos、Apollo |
+| 注册与发现 | Nacos、Consul、Eureka、etcd、内存注册表 |
+| 日志与监控 | 标准 logging、JSON 日志、Request ID、健康检查、Prometheus |
+| 服务通信 | HTTP 客户端、gRPC |
+| 后台任务 | HostedService、Scheduler、XXL-Job BEAN |
+| 通知与事件 | SMTP、进程内 Observer |
+
+组件配置和使用方法见 [组件文档](docs/components.md)。
+
+## 发布
+
+在 [Actions → Build Release](https://github.com/liangboceo/yuanboot-python/actions/workflows/Release.yml) 手动填写 `version`，选择 `prerelease`、`draft`。
+构建通过后，自动同步版本、创建 Git tag 和 GitHub Release，上传各平台可执行文件、wheel、源码包和校验文件。
+默认分支为 `master`，已发布 tag 保持不变。
+
+## 文档
+
+- [框架开发指南](docs/framework.md)
+- [组件配置与使用](docs/components.md)
+- [命令行、发布与依赖管理](docs/releases.md)
+
+## License
+
+[MIT](LICENSE)

yuanboot-0.1.5/README.md

@@ -0,0 +1,191 @@
+# yuanboot-python
+
+简单、轻量、快速的 Python 微服务框架，基于 FastAPI、Uvicorn 和依赖注入构建，支持 Web API、MVC、gRPC 与后台服务。Python 3.11+。
+
+[![Build](https://github.com/liangboceo/yuanboot-python/actions/workflows/ci.yml/badge.svg)](https://github.com/liangboceo/yuanboot-python/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/v/tag/liangboceo/yuanboot-python?label=release&sort=semver)](https://github.com/liangboceo/yuanboot-python/releases)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
+[![License](https://img.shields.io/github/license/liangboceo/yuanboot-python)](LICENSE)
+
+## 框架特色
+
+- 路由分组、MVC 控制器、请求校验、OpenAPI 和 WebSocket。
+- Singleton、Scoped、Transient 依赖注入与资源自动释放。
+- 统一宿主、应用生命周期、后台服务和优雅退出。
+- YAML / JSON、多环境配置、环境变量和远程配置热更新。
+- MySQL、Redis、Nacos 配置中心、服务注册与发现。
+- 结构化日志、请求追踪、健康检查、Prometheus 和 JWT。
+- HTTP 客户端、定时任务、SMTP、gRPC 和 XXL-Job BEAN 执行器。
+- `yuanbootctl-python` 提供六类项目模板、运行和构建命令。
+
+## 下载命令行工具
+
+从 [GitHub Releases](https://github.com/liangboceo/yuanboot-python/releases) 下载对应系统和架构的压缩包，解压后即可执行，无需预装 Python。
+
+| 系统 | 架构 | 文件后缀 |
+| --- | --- | --- |
+| Linux | amd64 / arm64 | `_linux_amd64.tar.gz` / `_linux_arm64.tar.gz` |
+| macOS | Intel / Apple Silicon | `_darwin_amd64.tar.gz` / `_darwin_arm64.tar.gz` |
+| Windows | amd64 | `_windows_amd64.zip` |
+
+例如 Linux amd64：
+
+```bash
+VERSION=0.1.5
+curl -fLO "https://github.com/liangboceo/yuanboot-python/releases/download/v${VERSION}/yuanbootctl-python_${VERSION}_linux_amd64.tar.gz"
+tar -xzf "yuanbootctl-python_${VERSION}_linux_amd64.tar.gz"
+chmod +x yuanbootctl-python
+./yuanbootctl-python --version
+./yuanbootctl-python new webapi -n demo
+cd demo
+../yuanbootctl-python run --profile dev
+```
+
+访问 [API 文档](http://127.0.0.1:8080/docs)。Windows 使用 `yuanbootctl-python.exe`。
+Release 同时提供 `SHA256SUMS`、wheel 和源码包。
+
+独立可执行文件包含 Python 运行时、框架和标准组件，可以直接创建、运行模板项目。
+业务增加其他 Python 依赖后，可使用 `run --python /path/to/.venv/bin/python` 选择业务环境。
+`build` 打包 Python 项目，需要业务环境安装 `build`，详见 [命令行与发布说明](docs/releases.md)。
+
+## 安装框架
+
+从公开 PyPI 安装框架或项目工具：
+
+```bash
+python -m pip install 'yuanboot[all]==0.1.5'
+# 也可通过工具包安装同版本框架和命令：
+python -m pip install yuanbootctl-python==0.1.5
+yuanbootctl-python --version
+```
+
+`yuanbootctl-python` 自动依赖同版本的 `yuanboot`，命令入口和模板资源统一由框架提供。
+`yuanbootctl-python[all]` 会安装全部标准组件。PyPI 安装方式需要 Python 3.11+。
+
+业务项目也可使用 Git tag 固定框架版本：
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install 'yuanboot[all] @ git+https://github.com/liangboceo/yuanboot-python.git@v0.1.5'
+yuanbootctl-python new mvc -n orders
+cd orders
+python -m pip install -e '.[dev,components]'
+yuanbootctl-python run --reload
+```
+
+按需选择 `mysql`、`redis`、`nacos`、`grpc` 等 extras；`all` 安装全部标准组件。
+框架和业务项目分别管理版本，业务项目提交自己的依赖锁文件。
+生成的项目默认保持 Git tag 依赖；使用 PyPI 时可将依赖改为 `yuanboot==0.1.5`、
+`yuanboot[all]==0.1.5`（gRPC 项目使用 `yuanboot[grpc]==0.1.5`）。
+
+## 项目模板
+
+| 模板 | 内容 |
+| --- | --- |
+| `simpleweb` | 最小 HTTP 应用与运维端点 |
+| `webapi` | API 路由、服务注入和请求校验 |
+| `mvc` | 控制器、服务层和 Jinja2 页面 |
+| `microservice` | Web API、监控和后台服务 |
+| `console` | 命令行宿主与后台任务 |
+| `grpc` | gRPC 服务与健康检查 |
+
+模板包含项目元数据、配置、Dockerfile、Compose、README 和 `spec` 开发文档。
+每个新项目默认提供以下文档，可离线查阅：
+
+```text
+README.md
+spec/
+├── yuanboot-python.md             # 框架使用说明
+├── components.md                 # 核心组件配置与使用
+└── backend-module-development.md  # 后端模块开发规范
+```
+
+```bash
+yuanbootctl-python new --list
+yuanbootctl-python new mvc -n my-app
+yuanbootctl-python new grpc -n rpc-demo
+yuanbootctl-python run --profile fat --port 9000
+yuanbootctl-python run --workers 2
+yuanbootctl-python build
+yuanbootctl-python version
+```
+
+## 简单示例
+
+```python
+from yuanboot.web import create_default_builder
+from yuanboot.web.endpoints import use_actuator
+
+
+def endpoints(router):
+    use_actuator(router)
+
+    @router.get("/info")
+    def info():
+        return {"info": "ok"}
+
+
+host = create_default_builder(endpoints).build()
+app = host.app
+
+if __name__ == "__main__":
+    host.run()
+```
+
+默认监听 `0.0.0.0:8080`。可通过宿主构建器配置服务注册、中间件、路由和生命周期。
+
+## 环境与配置
+
+支持 `dev / fat / uat / pro`，默认 `dev`。通过 `--profile` 或 `YUANBOOT_PROFILE` 选择环境。
+
+```text
+config.yml
+config_dev.yml
+config_fat.yml
+config_uat.yml
+config_pro.yml
+```
+
+配置优先级：默认值 < 基础配置 < 环境配置 < 远程配置 < 环境变量 < 命令行。
+MySQL、Redis 和 Nacos 等组件按配置启用；Nacos 注册 metadata 的 `yuanboot_env` 使用当前环境名。
+
+```yaml
+yuanboot:
+  application:
+    name: orders
+    server:
+      address: ":8080"
+```
+
+支持 `${ENV:default}` 插值和 Pydantic 模型绑定，敏感信息通过环境变量提供。
+
+## 核心组件
+
+| 能力 | 组件 |
+| --- | --- |
+| 数据与缓存 | MySQL / SQLAlchemy、Redis |
+| 配置中心 | Nacos、Apollo |
+| 注册与发现 | Nacos、Consul、Eureka、etcd、内存注册表 |
+| 日志与监控 | 标准 logging、JSON 日志、Request ID、健康检查、Prometheus |
+| 服务通信 | HTTP 客户端、gRPC |
+| 后台任务 | HostedService、Scheduler、XXL-Job BEAN |
+| 通知与事件 | SMTP、进程内 Observer |
+
+组件配置和使用方法见 [组件文档](docs/components.md)。
+
+## 发布
+
+在 [Actions → Build Release](https://github.com/liangboceo/yuanboot-python/actions/workflows/Release.yml) 手动填写 `version`，选择 `prerelease`、`draft`。
+构建通过后，自动同步版本、创建 Git tag 和 GitHub Release，上传各平台可执行文件、wheel、源码包和校验文件。
+默认分支为 `master`，已发布 tag 保持不变。
+
+## 文档
+
+- [框架开发指南](docs/framework.md)
+- [组件配置与使用](docs/components.md)
+- [命令行、发布与依赖管理](docs/releases.md)
+
+## License
+
+[MIT](LICENSE)