Metadata-Version: 2.4
Name: toms-fast
Version: 0.4.0
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: orjson>=3.9.0
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`

---

## 安装

```bash
# 使用 pip
pip install toms-fast

# 使用 uv（推荐）
uv pip install toms-fast
```

---

## 快速开始

### 使用脚手架创建新项目

```bash
# 创建完整项目（FastAPI + Celery）
tomskit init my_project

# 仅创建 FastAPI 项目
tomskit init my_project --type fastapi

# 仅创建 Celery 项目
tomskit init my_project --type celery
```

### 项目初始化

```bash
# 进入项目目录
cd my_project/backend

# 安装依赖
uv sync

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，配置数据库和 Redis

# 初始化数据库迁移
uv run alembic -c migrations/alembic.ini revision --autogenerate -m 'Initial migration'
uv run alembic -c migrations/alembic.ini upgrade head

# 运行 FastAPI
uv run uvicorn main:app --reload

# 运行 Celery Worker
uv run celery -A celery_app worker --loglevel=info
```

---

## CLI 命令

```bash
# 创建新项目
tomskit init <project_name> [--type full|fastapi|celery]

# 创建模块（Model + Controller + Schema）
tomskit scaffold module <name>

# 创建 Celery 任务
tomskit scaffold task <name>

# 创建扩展
tomskit scaffold extension <name>

# 初始化数据库迁移（已有项目）
tomskit migrations

# 初始化 Claude Code 支持
tomskit claude init
```

---

## 内置模块

| 模块 | 说明 |
|------|------|
| `tomskit.server` | FastAPI 扩展：资源管理、异常处理、中间件 |
| `tomskit.sqlalchemy` | SQLAlchemy 异步数据库集成，连接池管理 |
| `tomskit.redis` | Redis 异步客户端（单机/Sentinel/Cluster） |
| `tomskit.celery` | Celery 异步任务封装 |
| `tomskit.logger` | 结构化日志，支持追踪 ID |
| `tomskit.task` | 异步任务管理器 |
| `tomskit.tools` | Worker 管理工具（Gunicorn/Uvicorn） |
| `tomskit.utils` | 数据序列化工具 |

详细文档请参考各模块的 README：

- [Server 模块](src/tomskit/server/)
- [SQLAlchemy 模块](src/tomskit/sqlalchemy/README.md)
- [Redis 模块](src/tomskit/redis/README.md)
- [Celery 模块](src/tomskit/celery/README.md)
- [Logger 模块](src/tomskit/logger/README.md)
- [Task 模块](src/tomskit/task/README.md)
- [Tools 模块](src/tomskit/tools/README.md)
- [Utils 模块](src/tomskit/utils/README.md)

---

## 项目结构

```
src/tomskit/
├── server/        # FastAPI 扩展
├── sqlalchemy/    # 数据库集成
├── redis/         # Redis 客户端
├── celery/        # Celery 封装
├── logger/        # 日志管理
├── task/          # 异步任务管理
├── tools/         # Worker 管理
├── utils/         # 工具函数
└── cli/           # 脚手架工具
```

---

## 开发

```bash
# 克隆仓库
git clone https://github.com/tomszhou/toms-fast.git
cd toms-fast

# 安装开发依赖
uv sync --group dev

# 运行测试
pytest

# 代码检查
ruff check .
```

---

## 许可证

MIT License

---

## 相关链接

- [FastAPI](https://fastapi.tiangolo.com/)
- [SQLAlchemy](https://docs.sqlalchemy.org/)
- [Celery](https://docs.celeryq.dev/)
- [Redis](https://redis.io/docs/)
