aury-boot 0.0.10__tar.gz → 0.0.12__tar.gz

{aury_boot-0.0.10 → aury_boot-0.0.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aury-boot
-Version: 0.0.10
+Version: 0.0.12
 Summary: Aury Boot - 基于 FastAPI 生态的企业级 API 开发框架
 Requires-Python: >=3.13
 Requires-Dist: alembic>=1.17.2

{aury_boot-0.0.10 → aury_boot-0.0.12}/aury/boot/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.0.10'
-__version_tuple__ = version_tuple = (0, 0, 10)
+__version__ = version = '0.0.12'
+__version_tuple__ = version_tuple = (0, 0, 12)
 
 __commit_id__ = commit_id = None

{aury_boot-0.0.10 → aury_boot-0.0.12}/aury/boot/application/migrations/setup.py

@@ -117,6 +117,8 @@ def run_migrations_offline() -> None:
         dialect_opts={{"paramstyle": "named"}},
         compare_type=True,
         compare_server_default=True,
+        # 启用 batch 模式以更好地支持 SQLite 等不完整 DDL 的后端
+        render_as_batch=True,
     )
     with context.begin_transaction():
         context.run_migrations()
@@ -129,6 +131,8 @@ def _do_run_migrations(connection) -> None:
         target_metadata=target_metadata,
         compare_type=True,
         compare_server_default=True,
+        # 启用 batch 模式以更好地支持 SQLite 等不完整 DDL 的后端
+        render_as_batch=True,
     )
     with context.begin_transaction():
         context.run_migrations()

{aury_boot-0.0.10 → aury_boot-0.0.12}/aury/boot/commands/app.py

@@ -86,12 +86,14 @@ def _get_app() -> typer.Typer:
         from .generate import app as generate_app
         from .init import init
         from .migrate import app as migrate_app
+        from .pkg import app as pkg_app
         from .scheduler import app as scheduler_app
         from .server import app as server_app
         from .worker import app as worker_app
 
         app.command(name="init", help="🎯 初始化项目脚手架")(init)
         app.add_typer(add_app, name="add", help="➕ 添加可选模块")
+        app.add_typer(pkg_app, name="pkg", help="📦 包管理")
         app.add_typer(generate_app, name="generate", help="⚡ 代码生成器")
         app.add_typer(server_app, name="server", help="🖥️  服务器管理")
         app.add_typer(scheduler_app, name="scheduler", help="🕐 独立运行调度器")
@@ -162,6 +164,10 @@ def register_commands(
         from .add import app as add_app
         target_app.add_typer(add_app, name="add", help="➕ 添加可选模块")
     
+    # pkg 命令始终注册（包管理是通用功能）
+    from .pkg import app as pkg_app
+    target_app.add_typer(pkg_app, name="pkg", help="📦 包管理")
+    
     if include_generate:
         from .generate import app as generate_app
         target_app.add_typer(generate_app, name="generate", help="⚡ 代码生成器")
@@ -205,11 +211,12 @@ def get_command_modules() -> dict[str, type]:
         # {'init': <module>, 'add': <module>, 'server': <module>, ...}
         ```
     """
-    from . import add, docker, docs, generate, init, migrate, scheduler, server, worker
+    from . import add, docker, docs, generate, init, migrate, pkg, scheduler, server, worker
     
     return {
         "init": init,
         "add": add,
+        "pkg": pkg,
         "generate": generate,
         "server": server,
         "scheduler": scheduler,

{aury_boot-0.0.10 → aury_boot-0.0.12}/aury/boot/commands/init.py

@@ -928,6 +928,12 @@ def init(
     console.print("  4. 访问 API 文档：")
     console.print("     [cyan]http://127.0.0.1:8000/docs[/cyan]")
     console.print()
+    console.print("[bold]包管理（按需安装可选模块）：[/bold]")
+    console.print("  [cyan]aury pkg list[/cyan]               # 查看所有可用模块")
+    console.print("  [cyan]aury pkg preset[/cyan]             # 查看预设配置")
+    console.print("  [cyan]aury pkg install postgres redis[/cyan]  # 安装指定模块")
+    console.print("  [cyan]aury pkg install --preset api[/cyan]    # 按预设安装")
+    console.print()
     console.print("[bold]常用命令：[/bold]")
     console.print("  [cyan]aury generate crud user -i[/cyan]  # 生成 CRUD（交互式）")
     console.print("  [cyan]aury generate model user -i[/cyan] # 生成模型（交互式）")

aury_boot-0.0.12/aury/boot/commands/pkg.py

@@ -0,0 +1,471 @@
+"""包管理命令。
+
+用法：
+    aury pkg list                    # 列出所有可安装模块
+    aury pkg list --installed        # 已安装的模块
+    aury pkg preset                  # 列出预设
+    aury pkg preset api              # 查看预设详情
+    aury pkg install postgres redis  # 安装模块
+    aury pkg install --preset api    # 按预设安装
+    aury pkg remove redis            # 卸载模块
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+import subprocess
+import sys
+from typing import Annotated
+
+from rich.console import Console
+from rich.table import Table
+import typer
+
+console = Console()
+
+app = typer.Typer(
+    name="pkg",
+    help="包管理 - 安装/卸载 aury 生态模块",
+    no_args_is_help=True,
+)
+
+
+# ============================================================================
+# 数据定义
+# ============================================================================
+
+
+class Category(str, Enum):
+    """模块分类。"""
+
+    DATABASE = "database"
+    CACHE = "cache"
+    TASK = "task"
+    SCHEDULER = "scheduler"
+    ADMIN = "admin"
+    STORAGE = "storage"
+    ECOSYSTEM = "ecosystem"
+
+
+@dataclass
+class ModuleInfo:
+    """模块信息。"""
+
+    name: str
+    desc: str
+    usage: str
+    category: Category
+    deps: list[str]  # extras 的依赖包名
+    is_extra: bool = True  # True=extras, False=生态包
+    pkg: str | None = None  # 生态包的完整包名
+
+
+# Extras（aury-boot 的可选依赖）
+MODULES: dict[str, ModuleInfo] = {
+    # 数据库驱动
+    "postgres": ModuleInfo(
+        name="postgres",
+        desc="PostgreSQL 异步驱动",
+        usage="DatabaseManager 使用 PostgreSQL 时需要",
+        category=Category.DATABASE,
+        deps=["asyncpg"],
+    ),
+    "mysql": ModuleInfo(
+        name="mysql",
+        desc="MySQL 异步驱动",
+        usage="DatabaseManager 使用 MySQL 时需要",
+        category=Category.DATABASE,
+        deps=["aiomysql"],
+    ),
+    "sqlite": ModuleInfo(
+        name="sqlite",
+        desc="SQLite 异步驱动",
+        usage="DatabaseManager 使用 SQLite 时需要（本地开发推荐）",
+        category=Category.DATABASE,
+        deps=["aiosqlite"],
+    ),
+    # 缓存
+    "redis": ModuleInfo(
+        name="redis",
+        desc="Redis 客户端",
+        usage="CacheManager 使用 Redis 后端时需要",
+        category=Category.CACHE,
+        deps=["redis"],
+    ),
+    # 任务队列
+    "tasks": ModuleInfo(
+        name="tasks",
+        desc="Dramatiq 任务队列",
+        usage="TaskManager 异步任务时需要",
+        category=Category.TASK,
+        deps=["dramatiq", "kombu", "dramatiq-kombu-broker"],
+    ),
+    "rabbitmq": ModuleInfo(
+        name="rabbitmq",
+        desc="RabbitMQ 消息队列后端",
+        usage="TaskManager/EventBus 使用 RabbitMQ 时需要（需配合 tasks）",
+        category=Category.TASK,
+        deps=["amqp"],
+    ),
+    # 调度器
+    "scheduler": ModuleInfo(
+        name="scheduler",
+        desc="APScheduler 定时调度",
+        usage="SchedulerManager 定时任务时需要",
+        category=Category.SCHEDULER,
+        deps=["apscheduler"],
+    ),
+    # 管理后台
+    "admin": ModuleInfo(
+        name="admin",
+        desc="SQLAdmin 管理后台",
+        usage="启用 /admin 管理界面时需要",
+        category=Category.ADMIN,
+        deps=["sqladmin", "itsdangerous"],
+    ),
+    # 存储（extras）
+    "s3": ModuleInfo(
+        name="s3",
+        desc="S3 兼容存储（AWS/MinIO/OSS）",
+        usage="StorageManager 使用 S3 兼容存储时需要",
+        category=Category.STORAGE,
+        deps=["aury-sdk-storage[aws]"],
+    ),
+    # 生态包
+    "storage-aws": ModuleInfo(
+        name="storage-aws",
+        desc="AWS S3 兼容存储",
+        usage="StorageManager 使用 AWS S3/MinIO/OSS 时需要",
+        category=Category.ECOSYSTEM,
+        deps=[],
+        is_extra=False,
+        pkg="aury-sdk-storage[aws]",
+    ),
+    "storage-cos": ModuleInfo(
+        name="storage-cos",
+        desc="腾讯云 COS 原生存储",
+        usage="StorageManager 使用腾讯云 COS 时推荐（性能更好）",
+        category=Category.ECOSYSTEM,
+        deps=[],
+        is_extra=False,
+        pkg="aury-sdk-storage[cos]",
+    ),
+}
+
+
+@dataclass
+class PresetInfo:
+    """预设信息。"""
+
+    name: str
+    desc: str
+    modules: list[str]
+
+
+PRESETS: dict[str, PresetInfo] = {
+    "minimal": PresetInfo(
+        name="minimal",
+        desc="最小化（本地开发/测试）",
+        modules=["sqlite"],
+    ),
+    "api": PresetInfo(
+        name="api",
+        desc="API 服务（Web 接口 + 管理后台）",
+        modules=["postgres", "redis", "admin"],
+    ),
+    "worker": PresetInfo(
+        name="worker",
+        desc="后台 Worker（任务队列 + 调度器）",
+        modules=["postgres", "redis", "tasks", "rabbitmq", "scheduler"],
+    ),
+    "full": PresetInfo(
+        name="full",
+        desc="完整功能（所有模块）",
+        modules=["postgres", "redis", "tasks", "rabbitmq", "scheduler", "admin", "storage-cos"],
+    ),
+}
+
+
+# 分类显示名称
+CATEGORY_NAMES: dict[Category, str] = {
+    Category.DATABASE: "📦 数据库驱动",
+    Category.CACHE: "📦 缓存",
+    Category.TASK: "📦 任务队列",
+    Category.SCHEDULER: "📦 定时调度",
+    Category.ADMIN: "📦 管理后台",
+    Category.STORAGE: "📦 对象存储",
+    Category.ECOSYSTEM: "🌐 生态包",
+}
+
+
+# ============================================================================
+# 工具函数
+# ============================================================================
+
+
+def _get_installed_packages() -> set[str]:
+    """获取已安装的包名。"""
+    try:
+        result = subprocess.run(
+            [sys.executable, "-m", "pip", "list", "--format=freeze"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        installed = set()
+        for line in result.stdout.strip().split("\n"):
+            if "==" in line:
+                pkg_name = line.split("==")[0].lower().replace("-", "_")
+                installed.add(pkg_name)
+        return installed
+    except subprocess.CalledProcessError:
+        return set()
+
+
+def _is_module_installed(module: ModuleInfo) -> bool:
+    """检查模块是否已安装。"""
+    installed = _get_installed_packages()
+
+    if module.is_extra:
+        # 检查 deps 中的包是否已安装
+        for dep in module.deps:
+            # 处理 extras 语法，如 aury-sdk-storage[aws]
+            pkg_name = dep.split("[")[0].lower().replace("-", "_")
+            if pkg_name not in installed:
+                return False
+        return bool(module.deps)
+    else:
+        # 生态包：检查包名
+        if module.pkg:
+            pkg_name = module.pkg.split("[")[0].lower().replace("-", "_")
+            return pkg_name in installed
+    return False
+
+
+def _run_uv_command(args: list[str]) -> bool:
+    """运行 uv 命令。"""
+    cmd = ["uv", *args]
+    console.print(f"[dim]$ {' '.join(cmd)}[/dim]")
+    try:
+        subprocess.run(cmd, check=True)
+        return True
+    except subprocess.CalledProcessError as e:
+        console.print(f"[red]命令失败: {e}[/red]")
+        return False
+    except FileNotFoundError:
+        console.print("[red]错误: 未找到 uv，请先安装: pip install uv[/red]")
+        return False
+
+
+# ============================================================================
+# 命令实现
+# ============================================================================
+
+
+@app.command(name="list")
+def list_modules(
+    installed: Annotated[
+        bool,
+        typer.Option("--installed", "-i", help="仅显示已安装的模块"),
+    ] = False,
+) -> None:
+    """列出所有可安装的模块。"""
+    installed_pkgs = _get_installed_packages() if installed else None
+
+    # 按分类组织
+    by_category: dict[Category, list[ModuleInfo]] = {}
+    for module in MODULES.values():
+        if module.category not in by_category:
+            by_category[module.category] = []
+        by_category[module.category].append(module)
+
+    # 输出
+    for category in Category:
+        modules = by_category.get(category, [])
+        if not modules:
+            continue
+
+        # 过滤已安装
+        if installed:
+            modules = [m for m in modules if _is_module_installed(m)]
+            if not modules:
+                continue
+
+        console.print()
+        console.print(f"[bold]{CATEGORY_NAMES[category]}[/bold]")
+
+        table = Table(show_header=False, box=None, padding=(0, 2))
+        table.add_column("名称", style="cyan", width=15)
+        table.add_column("描述", width=30)
+        table.add_column("用途", style="dim")
+
+        for module in modules:
+            status = ""
+            if installed_pkgs is not None:
+                is_installed = _is_module_installed(module)
+                status = " [green]✓[/green]" if is_installed else ""
+            table.add_row(
+                f"{module.name}{status}",
+                module.desc,
+                f"→ {module.usage}",
+            )
+
+        console.print(table)
+
+    console.print()
+    console.print("[dim]提示: 使用 aury pkg install <模块名> 安装模块[/dim]")
+
+
+@app.command(name="preset")
+def list_presets(
+    name: Annotated[
+        str | None,
+        typer.Argument(help="预设名称（留空列出所有预设）"),
+    ] = None,
+) -> None:
+    """查看预设配置。"""
+    if name is None:
+        # 列出所有预设
+        console.print()
+        console.print("[bold]📋 可用预设[/bold]")
+        console.print()
+
+        table = Table(show_header=True, box=None, padding=(0, 2))
+        table.add_column("预设", style="cyan", width=12)
+        table.add_column("描述", width=35)
+        table.add_column("包含模块", style="dim")
+
+        for preset in PRESETS.values():
+            table.add_row(
+                preset.name,
+                preset.desc,
+                ", ".join(preset.modules),
+            )
+
+        console.print(table)
+        console.print()
+        console.print("[dim]提示: 使用 aury pkg preset <预设名> 查看详情[/dim]")
+        console.print("[dim]      使用 aury pkg install --preset <预设名> 安装[/dim]")
+    else:
+        # 查看指定预设
+        if name not in PRESETS:
+            console.print(f"[red]错误: 预设 '{name}' 不存在[/red]")
+            console.print(f"[dim]可用预设: {', '.join(PRESETS.keys())}[/dim]")
+            raise typer.Exit(1)
+
+        preset = PRESETS[name]
+        console.print()
+        console.print(f"[bold]📋 预设: {preset.name}[/bold]")
+        console.print(f"[dim]{preset.desc}[/dim]")
+        console.print()
+
+        console.print("[bold]包含模块:[/bold]")
+        for module_name in preset.modules:
+            module = MODULES.get(module_name)
+            if module:
+                installed = _is_module_installed(module)
+                status = "[green]✓ 已安装[/green]" if installed else "[dim]未安装[/dim]"
+                console.print(f"  • {module.name}: {module.desc} {status}")
+            else:
+                console.print(f"  • {module_name} [red](未知模块)[/red]")
+
+        console.print()
+        console.print(f"[dim]安装命令: aury pkg install --preset {name}[/dim]")
+
+
+@app.command(name="install")
+def install_modules(
+    modules: Annotated[
+        list[str] | None,
+        typer.Argument(help="要安装的模块名称"),
+    ] = None,
+    preset: Annotated[
+        str | None,
+        typer.Option("--preset", "-p", help="使用预设安装"),
+    ] = None,
+) -> None:
+    """安装模块。"""
+    if preset:
+        # 使用预设
+        if preset not in PRESETS:
+            console.print(f"[red]错误: 预设 '{preset}' 不存在[/red]")
+            console.print(f"[dim]可用预设: {', '.join(PRESETS.keys())}[/dim]")
+            raise typer.Exit(1)
+
+        preset_info = PRESETS[preset]
+        modules = preset_info.modules
+        console.print(f"[bold]📦 安装预设: {preset_info.name}[/bold]")
+        console.print(f"[dim]{preset_info.desc}[/dim]")
+        console.print()
+
+    if not modules:
+        console.print("[red]错误: 请指定要安装的模块，或使用 --preset[/red]")
+        raise typer.Exit(1)
+
+    # 收集要安装的包
+    extras_to_install: list[str] = []
+    pkgs_to_install: list[str] = []
+
+    for module_name in modules:
+        if module_name not in MODULES:
+            console.print(f"[yellow]警告: 模块 '{module_name}' 不存在，跳过[/yellow]")
+            continue
+
+        module = MODULES[module_name]
+        if module.is_extra:
+            extras_to_install.append(module.name)
+        else:
+            if module.pkg:
+                pkgs_to_install.append(module.pkg)
+
+    # 安装 extras
+    if extras_to_install:
+        extras_str = ",".join(extras_to_install)
+        console.print(f"[bold]安装 extras: {extras_str}[/bold]")
+        if not _run_uv_command(["add", f"aury-boot[{extras_str}]"]):
+            raise typer.Exit(1)
+
+    # 安装生态包
+    for pkg in pkgs_to_install:
+        console.print(f"[bold]安装生态包: {pkg}[/bold]")
+        if not _run_uv_command(["add", pkg]):
+            raise typer.Exit(1)
+
+    console.print()
+    console.print("[green]✅ 安装完成[/green]")
+
+
+@app.command(name="remove")
+def remove_modules(
+    modules: Annotated[
+        list[str],
+        typer.Argument(help="要卸载的模块名称"),
+    ],
+) -> None:
+    """卸载模块。"""
+    for module_name in modules:
+        if module_name not in MODULES:
+            console.print(f"[yellow]警告: 模块 '{module_name}' 不存在，跳过[/yellow]")
+            continue
+
+        module = MODULES[module_name]
+
+        if module.is_extra:
+            # extras 需要移除具体的依赖包
+            console.print(f"[bold]移除 {module.name} 的依赖...[/bold]")
+            for dep in module.deps:
+                pkg_name = dep.split("[")[0]  # 去掉 extras 语法
+                _run_uv_command(["remove", pkg_name])
+        else:
+            # 生态包直接移除
+            if module.pkg:
+                pkg_name = module.pkg.split("[")[0]
+                console.print(f"[bold]移除生态包: {pkg_name}[/bold]")
+                _run_uv_command(["remove", pkg_name])
+
+    console.print()
+    console.print("[green]✅ 卸载完成[/green]")
+
+
+__all__ = ["app"]

{aury_boot-0.0.10 → aury_boot-0.0.12}/aury/boot/commands/templates/project/aury_docs/10-storage.md.tpl

@@ -11,17 +11,20 @@ pip install "aury-sdk-storage[aws]"
 
 ## 10.2 基本用法（StorageManager）
 
-`StorageManager` 支持**命名多实例**，可以同时管理多个存储后端。
+`StorageManager` 支持**命名多实例**，内部使用 `aury-sdk-storage` 提供的 `StorageFactory.from_config()` 智能选择后端（COS 原生 / S3 兼容等），对上层暴露统一接口。
 
 ```python
 from aury.boot.infrastructure.storage import (
-    StorageManager, StorageConfig, StorageBackend, StorageFile,
+    StorageManager,
+    StorageConfig,
+    StorageBackend,
+    StorageFile,
 )
 
 # 默认实例
 storage = StorageManager.get_instance()
 await storage.initialize(StorageConfig(
-    backend=StorageBackend.COS,
+    backend=StorageBackend.COS,  # 自动选择 COS 原生 SDK 或 S3 兼容模式
     bucket_name="my-bucket-1250000000",
     region="ap-guangzhou",
     endpoint="https://cos.ap-guangzhou.myqcloud.com",
@@ -45,6 +48,12 @@ url = await storage.upload_file(
     )
 )
 
+# 批量上传
+urls = await storage.upload_files([
+    StorageFile(object_name="img/1.jpg", data=b"..."),
+    StorageFile(object_name="img/2.jpg", data=b"..."),
+])
+
 # 下载文件
 content = await storage.download_file("user/123/avatar.png")
 
@@ -58,7 +67,38 @@ exists = await storage.file_exists("user/123/avatar.png")
 await storage.delete_file("user/123/avatar.png")
 ```
 
-## 10.3 STS 临时凭证（前端直传）
+## 10.3 高级用法：直接使用 SDKStorageFactory / StorageType
+
+对于需要更精细控制后端类型（如在脚手架或基础设施层扩展存储实现）的场景，可以直接使用 SDK 导出的类型：
+
+```python
+from aury.boot.infrastructure.storage import (
+    COSStorage,
+    LocalStorage,
+    S3Storage,
+    SDKStorageFactory,  # SDK 工厂（基于 StorageType 枚举）
+    StorageConfig,
+    StorageFile,
+    StorageType,
+)
+
+# 使用 StorageType 创建后端
+config = StorageConfig(
+    backend=StorageType.COS,
+    bucket_name="my-bucket-1250000000",
+    region="ap-guangzhou",
+)
+
+backend = SDKStorageFactory.from_config(config)
+result = await backend.upload_file(
+    StorageFile(object_name="dev/test.txt", data=b"hello"),
+)
+print(result.url)
+```
+
+> 一般业务代码直接通过 `StorageManager` 即可，只有在需要自定义装配流程或编写基础设施扩展时才需要直接使用 `SDKStorageFactory` / `StorageType` / `COSStorage` 等类型。
+
+## 10.4 STS 临时凭证（前端直传）
 
 ```python
 from aury.sdk.storage.sts import (
@@ -95,11 +135,14 @@ return {{
 }}
 ```
 
-## 10.4 本地存储（开发测试）
+## 10.5 本地存储（开发测试）
 
 ```python
 from aury.boot.infrastructure.storage import (
-    StorageManager, StorageConfig, StorageBackend, StorageFile,
+    StorageManager,
+    StorageConfig,
+    StorageBackend,
+    StorageFile,
 )
 
 storage = StorageManager.get_instance()