toms-fast 0.2.1__py3-none-any.whl

tomskit/cli/templates/base.py

@@ -0,0 +1,348 @@
+"""
+基础模板模块
+包含所有项目类型都需要的基础文件模板
+"""
+
+from typing import Callable
+
+
+def _get_readme_content(project_name: str, project_type: str) -> str:
+    """根据项目类型生成 README 内容"""
+    project_type_names = {
+        "fastapi": "FastAPI",
+        "celery": "Celery",
+        "full": "FastAPI + Celery"
+    }
+    project_desc = project_type_names.get(project_type, project_type)
+    
+    # 基础内容
+    content = f'''# {project_name}
+
+基于 [toms-fast](https://github.com/tomszhou/toms-fast) 的 {project_desc} 项目脚手架。
+
+## 🚀 快速开始
+
+### 前置要求
+
+- Python >= 3.11
+- [uv](https://github.com/astral-sh/uv) (推荐使用 uv 管理依赖)
+
+### 1. 安装依赖
+
+使用 uv 安装项目依赖：
+
+```bash
+# 安装 uv (如果还没有安装)
+# macOS/Linux:
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# 或使用 pip:
+pip install uv
+
+# 安装项目依赖
+uv sync
+
+# 或安装开发依赖
+uv sync --group dev
+```
+
+### 2. 配置环境变量
+
+```bash
+cd backend
+cp .env.example .env
+# 编辑 .env 文件，配置数据库和 Redis 连接信息
+```
+
+'''
+    
+    # 根据项目类型添加运行说明
+    if project_type in ("fastapi", "full"):
+        content += '''### 3. 运行 FastAPI 应用
+
+```bash
+# 确保在 backend 目录下
+cd backend
+
+# 使用 uv 运行（推荐）
+uv run uvicorn main:app --reload
+
+# 或激活虚拟环境后运行
+source .venv/bin/activate  # Windows: .venv\\Scripts\\activate
+uvicorn main:app --reload
+
+# 或直接运行
+python main.py
+```
+
+### 4. 访问 API
+
+- API 文档: http://localhost:8000/docs (如果启用了文档)
+- 健康检查: http://localhost:8000/health
+- 用户 API: http://localhost:8000/api/v1/users
+
+'''
+    
+    if project_type in ("celery", "full"):
+        content += '''### 3. 运行 Celery Worker
+
+```bash
+# 确保在 backend 目录下
+cd backend
+
+# 使用 uv 运行（推荐）
+uv run celery -A celery_app worker --loglevel=info
+
+# 或激活虚拟环境后运行
+source .venv/bin/activate  # Windows: .venv\\Scripts\\activate
+celery -A celery_app worker --loglevel=info
+```
+
+### 4. 运行 Celery Beat（定时任务，可选）
+
+```bash
+cd backend
+uv run celery -A celery_app beat --loglevel=info
+```
+
+'''
+    
+    # 项目结构
+    content += f'''## 📁 项目结构
+
+```
+{project_name}/
+├── backend/              # 后端代码目录
+'''
+    
+    if project_type in ("fastapi", "full"):
+        content += '''│   ├── app/
+│   │   ├── controllers/      # 控制器层（API 路由）
+│   │   │   └── users/        # 用户控制器示例
+│   │   ├── models/           # 数据库模型
+│   │   ├── schemas/          # Pydantic 模型（请求/响应）
+│   │   ├── services/         # 业务逻辑层
+│   │   ├── middleware/       # 中间件目录
+│   │   │   ├── request_id.py      # 请求 ID 追踪
+│   │   │   └── resource_cleanup.py  # 资源清理
+│   │   └── utils/            # 工具函数
+│   ├── main.py               # FastAPI 应用入口
+'''
+    
+    if project_type in ("celery", "full"):
+        content += '''│   ├── celery_app.py          # Celery 应用入口
+│   ├── tasks/                # Celery 任务
+│   │   └── example_task.py   # 示例任务
+'''
+    
+    content += '''│   ├── tests/                # 测试文件
+│   ├── logs/                 # 日志目录
+│   ├── migrations/           # 数据库迁移目录
+│   ├── pyproject.toml        # 项目配置和依赖（使用 uv 管理）
+│   └── .env                  # 环境变量配置
+├── web/                  # 前端代码目录
+└── README.md             # 项目说明文档
+```
+
+'''
+    
+    # 使用指南
+    if project_type in ("fastapi", "full"):
+        content += '''## 📖 使用指南
+
+### 添加新控制器
+
+1. 在 `app/controllers/` 下创建新控制器目录
+2. 创建 `resources.py` 定义 Resource
+3. 在 `app/schemas/` 中创建对应的数据模型（请求/响应）
+4. 创建 `module.py` 定义控制器初始化函数
+5. 在 `main.py` 中调用初始化函数
+
+### 定义 Resource
+
+```python
+from tomskit.server import Resource, api_doc, register_resource
+
+@register_resource(module="users", path="/users", tags=["用户管理"])
+class UserResource(Resource):
+    @api_doc(
+        summary="获取用户列表",
+        response_model=list[UserResponse]
+    )
+    async def get(self, request: Request):
+        return []
+```
+
+'''
+    
+    if project_type in ("celery", "full"):
+        content += '''### 定义 Celery 任务
+
+```python
+from celery import shared_task
+from tomskit.celery import AsyncTaskRunner
+
+@shared_task(name="my_task", queue="default")
+def my_task(message: str):
+    runner = AsyncTaskRunner(async_my_task)
+    return runner.run(message)
+
+async def async_my_task(message: str):
+    # 实现异步任务逻辑
+    return f"处理完成: {message}"
+```
+
+'''
+    
+    content += '''## 🔗 相关链接
+
+- [toms-fast 文档](https://github.com/tomszhou/toms-fast)
+- [FastAPI 文档](https://fastapi.tiangolo.com/)
+- [Celery 文档](https://docs.celeryq.dev/)
+'''
+    
+    return content
+
+
+def get_base_templates(project_name: str, project_type: str = "full") -> dict[str, Callable[[], str]]:
+    """获取基础模板"""
+    return {
+        "env_example": lambda: '''# 应用配置
+APP_NAME=my-fastapi-app
+APP_ENV=development
+
+# Gunicorn 配置（生产环境）
+workers=4
+bind=0.0.0.0:8000
+daemon=False
+
+# Redis 配置
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_DB=0
+REDIS_PASSWORD=
+
+# 日志配置
+LOG_PREFIX=[MyApp]
+LOG_LEVEL=INFO
+LOG_DIR=logs
+LOG_NAME=apps
+LOG_USE_UTC=False
+
+# 数据库配置
+DB_HOST=localhost
+DB_PORT=3306
+DB_USERNAME=root
+DB_PASSWORD=password
+DB_DATABASE=mydb
+DB_CHARSET=utf8mb4
+DB_EXTRAS=
+
+# SQLAlchemy 配置
+SQLALCHEMY_DATABASE_URI_SCHEME=mysql+aiomysql
+SQLALCHEMY_DATABASE_SYNC_URI_SCHEME=mysql+pymysql
+SQLALCHEMY_POOL_SIZE=300
+SQLALCHEMY_MAX_OVERFLOW=10
+SQLALCHEMY_POOL_RECYCLE=3600
+SQLALCHEMY_POOL_PRE_PING=False
+SQLALCHEMY_ECHO=False
+''',
+        
+        "gitignore": lambda: '''# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual Environment
+venv/
+env/
+ENV/
+.venv
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Environment
+.env
+.env.local
+
+# Logs
+logs/
+*.log
+
+# Database
+*.db
+*.sqlite
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+run/
+*.pid
+''',
+        
+        "pyproject_toml": lambda: f'''[project]
+name = "{project_name}"
+version = "0.1.0"
+description = "基于 toms-fast 的 FastAPI 应用"
+requires-python = ">=3.11"
+dependencies = [
+    "toms-fast>=0.1.1",
+    "python-dotenv>=1.0.0",
+    "uvicorn[standard]>=0.27.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.uv]
+index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.5",
+    "pytest-asyncio>=0.26.0",
+    "httpx>=0.27.0",
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.mypy]
+python_version = "3.11"
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+''',
+        
+        "readme_md": lambda: _get_readme_content(project_name, project_type),
+        
+        "tests_init_py": lambda: "",
+    }

tomskit/cli/templates/celery.py

@@ -0,0 +1,101 @@
+"""
+Celery 模板模块
+包含所有 Celery 相关的文件模板
+"""
+
+from typing import Callable
+
+
+def get_celery_templates(project_name: str) -> dict[str, Callable[[], str]]:
+    """获取 Celery 模板"""
+    return {
+        "celery_app_py": lambda: f'''"""
+{project_name} Celery 应用入口
+"""
+
+from pathlib import Path
+from dotenv import load_dotenv
+from celery.signals import worker_process_init
+
+from extensions.ext_celery import init_app, get_celery_app
+from extensions import init_all_extensions
+
+# 加载环境变量
+env_path = Path(__file__).parent / ".env"
+if env_path.exists():
+    load_dotenv(env_path)
+else:
+    print("⚠️  警告: .env 文件不存在，请从 .env.example 复制并配置")
+
+# 初始化 Celery 应用（通过扩展）
+celery_app = init_app()
+
+# 统一初始化所有扩展（logger, database, redis 等）
+# 注意：celery_app 已经初始化，ext_celery 会检测到并跳过重复初始化
+init_all_extensions(celery_app)
+
+# Worker 启动时的初始化（如果需要额外的 worker 初始化逻辑）
+@worker_process_init.connect
+def init_worker(sender=None, **kwargs):
+    """Worker 进程启动时的初始化"""
+    # 扩展已经在 init_all_extensions 中初始化了
+    pass
+
+# 导入任务（确保任务被注册）
+from tasks import example_task  # noqa: E402, F401
+
+# 导出 celery_app 供其他地方使用
+__all__ = ["celery_app"]
+''',
+        
+        "tasks_init_py": lambda: '''"""
+Celery 任务模块
+"""
+
+# 导入所有任务，确保它们被注册到 Celery 应用
+from . import example_task  # noqa: F401
+
+__all__ = ["example_task"]
+''',
+        
+        "example_task_py": lambda: f'''"""
+示例 Celery 任务
+"""
+
+from celery import shared_task
+from tomskit.celery import AsyncTaskRunner
+
+
+@shared_task(name="{project_name}.example_task", queue="default")
+def example_task(message: str):
+    """
+    示例异步任务
+    
+    Args:
+        message: 要处理的消息
+        
+    Returns:
+        str: 处理结果
+    """
+    runner = AsyncTaskRunner(async_example_task)
+    return runner.run(message)
+
+
+async def async_example_task(message: str):
+    """
+    异步任务函数
+    
+    Args:
+        message: 要处理的消息
+        
+    Returns:
+        str: 处理结果
+    """
+    # TODO: 实现你的异步任务逻辑
+    # 可以使用 db.session 进行数据库操作
+    # 可以使用 redis_client 进行 Redis 操作
+    
+    print(f"处理消息: {{message}}")
+    return f"任务完成: {{message}}"
+''',
+    }

tomskit/cli/templates/extensions.py

@@ -0,0 +1,213 @@
+"""
+扩展模板模块
+包含所有扩展相关的文件模板
+"""
+
+from typing import Callable
+
+
+def get_extension_templates(project_name: str, project_type: str = "full") -> dict[str, Callable[[], str]]:
+    """获取扩展模板"""
+    # 根据项目类型决定是否包含 ext_celery
+    def _get_extensions_init_py():
+        celery_import = ""
+        celery_in_list = ""
+        if project_type in ("celery", "full"):
+            celery_import = "    ext_celery,\n"
+            celery_in_list = "    ext_celery,\n"
+        
+        return f'''"""
+扩展功能统一初始化
+"""
+
+import time
+from typing import Any
+
+from extensions import (
+    ext_logger,
+    ext_database,
+    ext_redis,
+{celery_import}    # 在这里导入更多扩展
+    # ext_mail,
+    # ext_storage,
+)
+
+# 扩展初始化顺序列表
+extensions = [
+    ext_logger,
+    ext_database,
+    ext_redis,
+{celery_in_list}    # 在这里添加更多扩展，按初始化顺序排列
+    # ext_mail,
+    # ext_storage,
+]
+
+
+def init_all_extensions(app: Any = None):
+    """
+    统一初始化所有扩展功能
+    
+    按 extensions 列表顺序初始化每个扩展，支持：
+    - is_enabled() 检查扩展是否启用
+    - init_app(app) 初始化扩展
+    - 记录初始化时间
+    
+    Args:
+        app: 应用实例（FastApp 或 AsyncCelery），可选
+    """
+    for ext in extensions:
+        short_name = ext.__name__.split(".")[-1]
+        
+        # 检查扩展是否启用
+        is_enabled = ext.is_enabled() if hasattr(ext, "is_enabled") else True
+        if not is_enabled:
+            print(f"⏭️  跳过 {{short_name}}（未启用）")
+            continue
+        
+        # 初始化扩展
+        try:
+            start_time = time.perf_counter()
+            ext.init_app(app)
+            end_time = time.perf_counter()
+            elapsed_ms = round((end_time - start_time) * 1000, 2)
+            print(f"✅ {{short_name}} 初始化成功 ({{elapsed_ms}} ms)")
+        except Exception as e:
+            print(f"❌ {{short_name}} 初始化失败: {{e}}")
+            raise
+'''
+    
+    return {
+        "extensions_init_py": _get_extensions_init_py,
+        
+        "extensions_logger_py": lambda: '''"""
+日志扩展初始化
+"""
+
+from tomskit.logger import setup_logging, LoggerConfig
+from typing import Any
+
+
+def is_enabled() -> bool:
+    """检查扩展是否启用"""
+    return True
+
+
+def init_app(app: Any = None):
+    """初始化日志系统"""
+    config = LoggerConfig()
+    setup_logging(config)
+''',
+        
+        "extensions_database_py": lambda: '''"""
+数据库扩展初始化
+"""
+
+from tomskit.sqlalchemy import db, DatabaseConfig
+from typing import Any
+
+
+def is_enabled() -> bool:
+    """检查扩展是否启用"""
+    return True
+
+
+def init_app(app: Any = None):
+    """初始化数据库连接池"""
+    config = DatabaseConfig()
+    db.initialize_session_pool(
+        config.SQLALCHEMY_DATABASE_URI,
+        config.SQLALCHEMY_ENGINE_OPTIONS
+    )
+''',
+        
+        "extensions_redis_py": lambda: '''"""
+Redis 扩展初始化
+"""
+
+from tomskit.redis import RedisClientWrapper, RedisConfig
+from typing import Any
+
+
+def is_enabled() -> bool:
+    """检查扩展是否启用"""
+    return True
+
+
+def init_app(app: Any = None):
+    """初始化 Redis 连接"""
+    config = RedisConfig()
+    RedisClientWrapper.initialize(config.model_dump())
+''',
+        
+        "extensions_celery_py": lambda: f'''"""
+Celery 扩展初始化
+"""
+
+from pathlib import Path
+from typing import Any
+from dotenv import load_dotenv
+
+from tomskit.celery import AsyncCelery, CeleryConfig
+
+# 全局 Celery 应用实例
+celery_app: AsyncCelery | None = None
+
+
+def is_enabled() -> bool:
+    """检查扩展是否启用"""
+    return True
+
+
+def init_app(app: Any = None) -> AsyncCelery:
+    """
+    初始化 Celery 应用
+    
+    Args:
+        app: 应用实例（FastApp 或 AsyncCelery），可选
+        
+    Returns:
+        AsyncCelery: Celery 应用实例
+    """
+    global celery_app
+    
+    # 如果已经初始化，直接返回
+    if celery_app is not None:
+        return celery_app
+    
+    # 如果传入的是 AsyncCelery 实例，说明已经在 celery_app.py 中创建了
+    # 这种情况下只需要保存引用，不需要重新创建
+    if isinstance(app, AsyncCelery):
+        celery_app = app
+        return celery_app
+    
+    # 加载环境变量
+    env_path = Path(__file__).parent.parent / ".env"
+    if env_path.exists():
+        load_dotenv(env_path)
+    
+    # 创建 Celery 配置
+    celery_config = CeleryConfig()
+    
+    # 创建 Celery 应用
+    celery_app = AsyncCelery(
+        '{project_name}',
+        broker=celery_config.CELERY_BROKER_URL,
+        backend=celery_config.CELERY_RESULT_BACKEND
+    )
+    
+    # 应用配置
+    celery_app.from_mapping(celery_config.get_celery_config_dict())
+    
+    # 设置应用根路径
+    celery_app.set_app_root_path(Path(__file__).parent.parent)
+    
+    return celery_app
+
+
+def get_celery_app() -> AsyncCelery:
+    """获取 Celery 应用实例"""
+    if celery_app is None:
+        raise RuntimeError("Celery app is not initialized. Call init_app() first.")
+    return celery_app
+''',
+    }