toms-fast 0.2.1__py3-none-any.whl

toms_fast-0.2.1.dist-info/METADATA

@@ -0,0 +1,467 @@
+Metadata-Version: 2.4
+Name: toms-fast
+Version: 0.2.1
+Summary: 基于 FastAPI 的异步基础工具库，提供 Redis、SQLAlchemy、Celery、日志管理等企业级基础设施的统一封装，简化异步 API 与服务端应用开发（import 包名：tomskit）
+Author-email: AllinOneAI Team <ai@aioai.cc>
+Requires-Python: >=3.11
+Requires-Dist: alembic>=1.13.0
+Requires-Dist: celery>=5.5.2
+Requires-Dist: fastapi>=0.115.12
+Requires-Dist: pydantic-settings>=2.9.1
+Requires-Dist: redis>=6.0.0
+Requires-Dist: sqlalchemy>=2.0.40
+Description-Content-Type: text/markdown
+
+# toms-fast
+
+**toms-fast** 是一个基于 **FastAPI** 的异步基础工具库（Async Infrastructure Toolkit），  
+用于简化和规范企业级异步 API 与服务端应用的开发。
+
+> **PyPI 名称**：`toms-fast`  
+> **Python import 包名**：`tomskit`  
+> **Python 版本要求**：`>=3.11`
+
+该项目沉淀了在实际生产环境中反复验证的工程实践，  
+将 **Redis、SQLAlchemy、Celery、FastAPI** 等常用组件进行统一封装，
+帮助开发者专注于业务逻辑，而不是基础设施细节。
+
+---
+
+## ✨ 特性（Features）
+
+- ⚡ **完全异步**：基于 FastAPI / ASGI 的异步架构，支持高并发场景
+- 🧠 **模块化设计**：清晰的模块边界，适合中大型项目
+- 🧩 **开箱即用**：内置常用基础能力，无需重复造轮子
+- 🔒 **生产就绪**：经过生产环境验证，稳定可靠
+- 📦 **类型安全**：完整的类型注解支持，提升开发体验
+- 🛠️ **配置管理**：基于 Pydantic Settings 的统一配置管理
+- 📚 **完整文档**：每个模块都有详细的 README 和使用示例
+
+### 内置能力
+
+- **Redis**：异步/同步客户端，支持单机、Sentinel、Cluster 模式
+- **SQLAlchemy**：异步数据库集成，支持连接池管理和分页查询
+- **Celery**：异步任务队列封装，支持在任务中运行异步函数
+- **Logger**：结构化日志配置，支持追踪 ID 和多类型日志分离
+- **Server**：FastAPI 扩展，提供资源管理、异常处理、中间件等
+- **Utils**：数据序列化工具，支持异步数据源
+- **Task**：异步任务管理器，支持批量任务执行
+- **Tools**：Worker 管理工具，支持 Gunicorn/Uvicorn 监控
+
+---
+
+## 📦 安装（Installation）
+
+> **💡 推荐使用虚拟环境**：为了避免依赖冲突和保持环境隔离，强烈建议在虚拟环境中安装和使用 `toms-fast`。
+
+### 创建虚拟环境
+
+```bash
+# 使用 uv 创建虚拟环境（推荐）
+uv venv
+source .venv/bin/activate  # Linux/Mac
+# 或 .venv\Scripts\activate  # Windows
+
+# 或使用 Python 内置 venv
+python -m venv .venv
+source .venv/bin/activate  # Linux/Mac
+# 或 .venv\Scripts\activate  # Windows
+```
+
+### 使用 pip
+
+```bash
+pip install toms-fast
+```
+
+### 使用 uv（推荐）
+
+```bash
+uv pip install toms-fast
+```
+
+### 使用 poetry
+
+```bash
+poetry add toms-fast
+```
+
+---
+
+## 🚀 快速开始（Quick Start）
+
+### 使用脚手架创建新项目（推荐）
+
+使用 `toms-fast` 提供的脚手架工具，可以快速创建一个完整的项目结构：
+
+```bash
+# 1. 创建虚拟环境（如果还没有）
+uv venv
+source .venv/bin/activate  # Linux/Mac
+# 或 .venv\Scripts\activate  # Windows
+
+# 2. 安装 toms-fast
+uv pip install toms-fast
+
+# 3. 使用脚手架创建新项目
+fastapi-cli init my_project --type full
+
+# 4. 进入项目目录
+cd my_project
+
+# 5. 安装项目依赖
+uv sync
+
+# 6. 配置环境变量
+cp .env.example .env
+# 编辑 .env 文件，配置数据库和 Redis 连接信息
+
+# 7. 初始化数据库迁移（FastAPI 项目）
+uv run alembic revision --autogenerate -m 'Initial migration'
+uv run alembic upgrade head
+
+# 8. 运行应用
+uv run uvicorn main:app --reload
+```
+
+**项目类型说明：**
+- `full`（默认）：包含 FastAPI 和 Celery 的完整项目
+- `fastapi`：仅 FastAPI 项目
+- `celery`：仅 Celery 项目
+
+**更多脚手架选项：**
+```bash
+# 查看帮助
+fastapi-cli init --help
+
+# 指定目标目录
+fastapi-cli init my_project -d /path/to/target
+
+# 创建仅 FastAPI 项目
+fastapi-cli init my_project --type fastapi
+
+# 创建仅 Celery 项目
+fastapi-cli init my_project --type celery
+```
+
+### 基础示例
+
+```python
+from fastapi import FastAPI
+from tomskit.logger import setup_logging, LoggerConfig
+from tomskit.redis import RedisClientWrapper, RedisConfig
+from tomskit.sqlalchemy import db, DatabaseConfig
+
+# 初始化日志
+log_config = LoggerConfig()
+setup_logging(log_config)
+
+# 初始化 Redis
+redis_config = RedisConfig()
+RedisClientWrapper.initialize(redis_config.model_dump())
+
+# 初始化数据库
+db_config = DatabaseConfig()
+db.initialize_session_pool(
+    db_config.SQLALCHEMY_DATABASE_URI,
+    db_config.SQLALCHEMY_ENGINE_OPTIONS
+)
+
+app = FastAPI()
+
+@app.get("/")
+async def root():
+    return {"message": "Hello from toms-fast!"}
+```
+
+### 使用 Server 模块创建 RESTful API
+
+```python
+from tomskit.server import FastApp, FastModule, register_resource, Resource, api_doc
+from fastapi import Request
+from pydantic import BaseModel
+
+# 创建主应用
+app = FastApp(title="My API")
+
+# 创建模块
+user_module = FastModule(name="users")
+user_module.create_router(prefix="/api/v1")
+
+# 定义响应模型
+class UserResponse(BaseModel):
+    id: int
+    name: str
+    email: str
+
+# 注册资源
+@register_resource(module="users", path="/users", tags=["User Management"])
+class UserResource(Resource):
+    @api_doc(
+        summary="获取用户列表",
+        response_model=list[UserResponse]
+    )
+    async def get(self, request: Request):
+        return [
+            {"id": 1, "name": "Alice", "email": "alice@example.com"},
+            {"id": 2, "name": "Bob", "email": "bob@example.com"}
+        ]
+
+# 自动注册资源
+user_module.auto_register_resources()
+
+# 挂载模块
+app.mount("/api", user_module)
+```
+
+---
+
+## 📁 项目结构（Project Structure）
+
+```
+src/tomskit/
+├── server/        # FastAPI 扩展：资源管理、异常处理、中间件
+├── redis/         # Redis 客户端：异步/同步，支持多种模式
+├── sqlalchemy/    # SQLAlchemy 集成：异步数据库操作和分页
+├── celery/        # Celery 封装：异步任务队列支持
+├── logger/        # 日志管理：结构化日志和追踪 ID
+├── task/          # 异步任务管理：批量任务执行
+├── tools/         # 工具模块：Worker 管理等
+└── utils/         # 工具函数：数据序列化、响应处理
+```
+
+---
+
+## 📖 模块文档
+
+每个模块都有详细的 README 文档，包含完整的使用示例：
+
+- [**Server 模块**](src/tomskit/server/) - FastAPI 扩展，资源管理、异常处理
+- [**Redis 模块**](src/tomskit/redis/README.md) - Redis 客户端使用指南
+- [**SQLAlchemy 模块**](src/tomskit/sqlalchemy/README.md) - 数据库操作指南
+- [**Celery 模块**](src/tomskit/celery/README.md) - 异步任务队列指南
+- [**Logger 模块**](src/tomskit/logger/README.md) - 日志配置指南
+- [**Utils 模块**](src/tomskit/utils/README.md) - 数据序列化指南
+- [**Task 模块**](src/tomskit/task/README.md) - 异步任务管理指南
+- [**Tools 模块**](src/tomskit/tools/README.md) - Worker 管理指南
+
+---
+
+## 🔧 核心模块使用示例
+
+### Redis 使用
+
+```python
+from tomskit.redis import RedisClientWrapper, redis_client, RedisConfig
+
+# 初始化
+config = RedisConfig()
+RedisClientWrapper.initialize(config.model_dump())
+
+# 使用
+await redis_client.set("key", "value")
+value = await redis_client.get("key")
+```
+
+### 数据库使用
+
+```python
+from tomskit.sqlalchemy import db, DatabaseConfig
+
+# 初始化
+config = DatabaseConfig()
+db.initialize_session_pool(
+    config.SQLALCHEMY_DATABASE_URI,
+    config.SQLALCHEMY_ENGINE_OPTIONS
+)
+
+# 使用
+session = db.create_session()
+user = await session.get(User, user_id)
+await db.close_session(session)
+```
+
+### Celery 任务
+
+```python
+from tomskit.celery import AsyncCelery, AsyncTaskRunner
+from celery import shared_task
+
+celery_app = AsyncCelery('myapp', broker='redis://localhost:6379/0')
+
+@celery_app.task
+def my_task():
+    runner = AsyncTaskRunner(async_my_task)
+    return runner.run()
+
+async def async_my_task():
+    # 异步任务逻辑
+    return "done"
+```
+
+### 日志配置
+
+```python
+from tomskit.logger import setup_logging, LoggerConfig, set_app_trace_id
+import uuid
+
+# 初始化
+config = LoggerConfig(LOG_LEVEL="INFO")
+setup_logging(config)
+
+# 在请求中设置追踪 ID
+trace_id = str(uuid.uuid4())
+set_app_trace_id(trace_id)
+```
+
+---
+
+## ⚙️ 环境变量配置
+
+`toms-fast` 通过环境变量进行配置，应用需要显式加载 `.env` 文件（如使用 `python-dotenv`）。
+
+### Redis 配置
+
+```bash
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_DB=0
+REDIS_PASSWORD=
+REDIS_USE_SENTINEL=false
+REDIS_USE_CLUSTERS=false
+```
+
+### 数据库配置
+
+```bash
+DB_HOST=localhost
+DB_PORT=3306
+DB_USERNAME=user
+DB_PASSWORD=password
+DB_DATABASE=mydb
+DB_CHARSET=utf8mb4
+```
+
+### 日志配置
+
+```bash
+LOG_PREFIX=[MyApp]
+LOG_LEVEL=INFO
+LOG_DIR=logs
+LOG_NAME=apps
+LOG_USE_UTC=false
+```
+
+### SQLAlchemy 配置
+
+```bash
+SQLALCHEMY_POOL_SIZE=300
+SQLALCHEMY_MAX_OVERFLOW=10
+SQLALCHEMY_POOL_RECYCLE=3600
+SQLALCHEMY_POOL_PRE_PING=false
+```
+
+更多配置项请参考各模块的 README 文档。
+
+---
+
+## 🛠️ 开发环境（Development）
+
+### 克隆仓库
+
+```bash
+git clone https://github.com/tomszhou/toms-fast.git
+cd toms-fast
+```
+
+### 安装开发依赖
+
+```bash
+# 使用 uv（推荐）
+uv venv
+source .venv/bin/activate
+uv pip install -e ".[dev]"
+
+# 或使用 pip
+pip install -e ".[dev]"
+```
+
+### 运行测试
+
+```bash
+pytest
+```
+
+### 代码格式化
+
+```bash
+ruff format .
+ruff check .
+```
+
+---
+
+## 📋 适用场景（Use Cases）
+
+- ✅ 企业级 FastAPI 后端服务
+- ✅ 高并发异步 API 开发
+- ✅ 需要统一基础设施规范的团队
+- ✅ 中大型 Python 服务端项目
+- ✅ 微服务架构应用
+- ✅ 需要异步任务处理的系统
+
+---
+
+## 🤝 贡献（Contributing）
+
+欢迎贡献代码！🎉
+
+在提交 PR 前，请确保：
+
+- ✅ 代码风格一致（遵循项目规范）
+- ✅ 所有测试通过
+- ✅ 遵循现有模块设计约定
+- ✅ 添加必要的文档和示例
+- ✅ 更新相关的 README 文件
+
+### 贡献流程
+
+1. Fork 本仓库
+2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
+3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
+4. 推送到分支 (`git push origin feature/AmazingFeature`)
+5. 开启 Pull Request
+
+---
+
+## 📄 许可证（License）
+
+本项目采用 **MIT License**。
+
+---
+
+## 🔗 相关链接
+
+- [FastAPI 官方文档](https://fastapi.tiangolo.com/)
+- [SQLAlchemy 官方文档](https://docs.sqlalchemy.org/)
+- [Celery 官方文档](https://docs.celeryq.dev/)
+- [Redis 官方文档](https://redis.io/docs/)
+
+---
+
+## 📝 更新日志
+
+查看 [GIT_SUMMARY.md](GIT_SUMMARY.md) 了解详细的提交历史。
+
+---
+
+## 💬 支持
+
+如有问题或建议，请通过以下方式联系：
+
+- 提交 [Issue](https://github.com/tomszhou/toms-fast/issues)
+- 发送邮件至项目维护者
+
+---
+
+**Made with ❤️ by AllinOneAI Team**

toms_fast-0.2.1.dist-info/RECORD

@@ -0,0 +1,60 @@
+tomskit/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tomskit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tomskit/celery/README.md,sha256=ruFKbW41mYpS92Z4GUgewEh6tSznIm7OGCCZzTUnOE4,22426
+tomskit/celery/__init__.py,sha256=1LzaZEuIsWWABlslVgNtgZeQ95XbGiCbqSFaH98kzt4,206
+tomskit/celery/celery.py,sha256=F88DfrlYxJS9swOGI0-8Vb8adnSU3PijocZwe2sweRA,11079
+tomskit/celery/config.py,sha256=5V6zwYJ3BgCwfTTWj8gvXYdr3yNgwnDALAmyR7PqlrI,13267
+tomskit/cli/__init__.py,sha256=_QSzPGmbrY4WhQJqJY0JxHpQLrLtO1H2dT2dJgJka1M,7653
+tomskit/cli/__main__.py,sha256=O1mjT1vhKNY0-Q5wAfJsDiyiAq4WJ9y_5AsHBFFh6sA,115
+tomskit/cli/scaffold.py,sha256=wuvy5J-Ktcg07GnBSpEoWVm7zJw5JvD7OvPaAu2B2rs,5263
+tomskit/cli/templates_config.py,sha256=SRv8MuAv2IELPAVGyMuihqx1hmM9Gk51vEjEJlmyVJ4,3856
+tomskit/cli/templates/__init__.py,sha256=NKaJeX1GrcO8Jwra3Z_XTWNtKJfaR1cmjRdf1H0nric,1237
+tomskit/cli/templates/base.py,sha256=gv4Q8OaLlUKDFKqF6TLmLF3VdzU7_l_mBsemLF2eXBY,7460
+tomskit/cli/templates/celery.py,sha256=rRx8uAXe2tmsGbX_iO5UHGJjS55r2leBuB2HNj2bH4c,2505
+tomskit/cli/templates/extensions.py,sha256=YIYSycGdFduhrr3jytGxbUAHII9b8chFxZozZ6ZdkQE,5194
+tomskit/cli/templates/fastapi.py,sha256=H6xzdmfD-ntQagh6-u08J_kIBjNjtlu_fEySLtVPwww,9913
+tomskit/cli/templates/migrations.py,sha256=DdovFsmJZ2NtvrRZbyjMdwSL8A-sg-xusi_5jRIIpqw,7929
+tomskit/logger/README.md,sha256=qam61LnmMauljcNK-OsVqUuSYd7EqYPpqsHY0wi0vdA,14872
+tomskit/logger/__init__.py,sha256=xdPo7dLn1_OqB1_wTh1hIVZTZRL4mko8Mw5VPcIpRBg,216
+tomskit/logger/config.py,sha256=ULLkCiK9wSh64Ym2bhiUowb7pM3RPIIYgljDI-YqbkM,2943
+tomskit/logger/logger.py,sha256=kDSz55D2-oI9u74VqeQWAplVdK-2mk1kck2KL6ydoxA,11766
+tomskit/redis/README.md,sha256=yXDMF4UXv1FyJaVDT7HmGg9EYBR3ZJBT5XsEkxAdgAE,13888
+tomskit/redis/__init__.py,sha256=bgdv7pzs-vscj6yZh82WyKQ0z5bOH7SB-l_rSigiyJA,257
+tomskit/redis/config.py,sha256=FHmrYLo1eg-isiva0i_apzJI86heU_I7nvoYdOCulR4,2456
+tomskit/redis/redis_pool.py,sha256=nby0JLIbxxgveB5dUEAY2jGjSLN5Vcalnli1q534iMI,3345
+tomskit/redis/redis_sync.py,sha256=icxDMXI-ZPIxgIfIRqKLYVk8YzqybUCYd4pGbZPSJC8,2225
+tomskit/server/__init__.py,sha256=wpwtGeahZjhWqFteULiUg-B2Vltc5-cm4fYHqDmSGMk,1104
+tomskit/server/config.py,sha256=qvw1r7nDI4_24HS_OSMlTZuFxyDWleiX1569SubMkiU,4231
+tomskit/server/exceptions.py,sha256=uNufXWOYzK_50Bx5-cpB6NnD0aQXnfvLP0mGjegwIO8,14332
+tomskit/server/middleware.py,sha256=5s8iNLYyYZvTX2qZjOUTDIVHY-XGLMASK2L0lWXBlfA,13543
+tomskit/server/parser.py,sha256=va8hMrvosxhOPfio7L9Tofv-uXSMka7GaUCs2q1Sx9A,11822
+tomskit/server/resource.py,sha256=wnzFhZmEWekr6nDbyCh-ituta4MJXjxPpnjIInWJhGY,18166
+tomskit/server/server.py,sha256=e6bT7EXKL_h-eUFGHoVjBMXRBl8Hs0cu78cBXayl-V0,10273
+tomskit/server/type.py,sha256=DiFY2IqKyrndh9_F7sEkyemwhQuROM2l-iPSIH4hBs4,9006
+tomskit/sqlalchemy/README.md,sha256=UIkOES4bhhR_Hh3RXxj168C3uxVtlKyDGbbhiNDhhTM,16886
+tomskit/sqlalchemy/__init__.py,sha256=uSW-bU_wsQdilgRgTfWPyNgmep61tXHO8NulH-gkrGA,567
+tomskit/sqlalchemy/config.py,sha256=hurSCfyeas_a42ZhfQWqu9LTJ3J-Okr5rd-D8tzOp0s,3625
+tomskit/sqlalchemy/database.py,sha256=ptTjRAS5dzqYpbxp6BlzBZSwcolQtSWNwNzNMueSkv0,4462
+tomskit/sqlalchemy/pagination.py,sha256=PxkFlgEcbSiu1ogouBqUEiTTSRQXvVr3xrc16Nqpv1U,10912
+tomskit/sqlalchemy/property.py,sha256=wHcjDXBbA9Ci_v8Y44uXwFNxEuekGcXEtN-tASU5wIY,563
+tomskit/sqlalchemy/sqlalchemy.py,sha256=yBXgFLhFYwfogO7NRv5VuPjz8QNzr-if68ErGN0S4mg,4291
+tomskit/sqlalchemy/types.py,sha256=MHaa5c5jwRWo9D-EXlgS3TyDEMoUcQQIraSg2RXGP10,779
+tomskit/task/README.md,sha256=lMnFuDqS2ZqmTXbwAeJtA4dECl3yfYx1yKc0wl6svWQ,2069
+tomskit/task/__init__.py,sha256=yRPwicyaflVW6PgS2GEFB2xs1zC16pW0aNA69crlLJQ,76
+tomskit/task/task_manager.py,sha256=5hHWrYql8thV7FRn9tDe9UBwGRBjROytVBrzkslRVOg,4010
+tomskit/tools/README.md,sha256=t63J8jqqbHl8FjO1eog-QNLRnX_NJkzbEbnCBQ4KYWg,1916
+tomskit/tools/__init__.py,sha256=GutxBG9Jn4QhM4ySWdvjix0nuMennQnZHvLamFjuGew,479
+tomskit/tools/config.py,sha256=u0HtNm67ukeiEUzgZMJuDlROe-c6Bw_fFyqhK2bI6cU,1938
+tomskit/tools/warnings.py,sha256=3IlZFW4zPpyyZx_5c0S0KCOh-Z4DR8HbXa-46p5f74Y,1107
+tomskit/tools/woker.py,sha256=L7vQ5ZeHcWqfN-wmddne6AYbRUzPAxZZTOLFTfwhAac,2747
+tomskit/utils/README.md,sha256=XxWJ1-e4XOG9-Vf8xGTZEsFBmXnLgjPPpmiDA-2nQO8,15833
+tomskit/utils/README_SERIALIZER.md,sha256=3MnE-BUL5v-RKJk7E5qZpBf4peKuL5um2Oiqab9_4Ms,15916
+tomskit/utils/__init__.py,sha256=zaVS-h0jM7di9j-JajRYz5XirmaBqX1nhVC4W6dQV2Y,577
+tomskit/utils/fields.py,sha256=hpuBkYs6fDqpHmTuhQalUcDew9oWznwYnja48b-X0ow,13476
+tomskit/utils/marshal_utils.py,sha256=n0q88Kx7TtOgwa3BkizEq-rkx13tM8UlngvTKwv1Lfs,4635
+tomskit/utils/response_utils.py,sha256=a2nig5UZ6542SfgSPiqug6lgj-5O_suhKAYCbuevU9U,312
+tomskit/utils/serializers.py,sha256=T_V0U7DFUWz2z10sT_DpLcPmVu1wjdC4_m-45ABW22A,17368
+toms_fast-0.2.1.dist-info/METADATA,sha256=KTOooK4EOJiMxcnlGEqV3T6csp1MkPRApAdJ-Wy8SIA,11115
+toms_fast-0.2.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+toms_fast-0.2.1.dist-info/entry_points.txt,sha256=_atR7y2awl5n-wASsJXI1FkdSeKo0_m8QwJFMFLc4k0,49
+toms_fast-0.2.1.dist-info/RECORD,,

toms_fast-0.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

toms_fast-0.2.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+fastapi-cli = tomskit.cli:main