fastapi-augment 0.1.0__py3-none-any.whl

fastapi_augment/db/sqlalchemy/migrate.py

@@ -0,0 +1,356 @@
+"""
+@Author     : zarkhan
+@CreateDate : 2026/9/5
+@Description: 数据库迁移脚本
+"""
+import argparse
+import subprocess
+import sys
+from logging import getLogger
+from os import environ
+from pathlib import Path
+
+from alembic import command
+from alembic.config import Config
+
+_logger = getLogger(__name__)
+
+# ===================== alembic.ini 模板 =====================
+
+_ALEMBIC_INI_TEMPLATE = """\
+# A generic, single database configuration.
+
+[alembic]
+# path to migration scripts.
+# this is typically a path given in POSIX (e.g. forward slashes)
+# format, relative to the token %(here)s which refers to the location of this
+# ini file
+script_location = fastapi_augment.db.sqlalchemy:alembic
+version_locations = %(here)s/migrations/versions
+
+# template used to generate migration file names; The default value is %%(rev)s_%%(slug)s
+# Uncomment the line below if you want the files to be prepended with date and time
+# see https://alembic.sqlalchemy.org/en/latest/tutorial.html#editing-the-ini-file
+# for all available tokens
+# file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s
+# Or organize into date-based subdirectories (requires recursive_version_locations = true)
+# file_template = %%(year)d/%%(month).2d/%%(day).2d_%%(hour).2d%%(minute).2d_%%(second).2d_%%(rev)s_%%(slug)s
+
+# sys.path path, will be prepended to sys.path if present.
+# defaults to the current working directory.  for multiple paths, the path separator
+# is defined by "path_separator" below.
+prepend_sys_path = .
+
+
+# timezone to use when rendering the date within the migration file
+# as well as the filename.
+# If specified, requires the tzdata library which can be installed by adding
+# `alembic[tz]` to the pip requirements.
+# string value is passed to ZoneInfo()
+# leave blank for localtime
+# timezone =
+
+# max length of characters to apply to the "slug" field
+# truncate_slug_length = 40
+
+# set to 'true' to run the environment during
+# the 'revision' command, regardless of autogenerate
+# revision_environment = false
+
+# set to 'true' to allow .pyc and .pyo files without
+# a source .py file to be detected as revisions in the
+# versions/ directory
+# sourceless = false
+
+# version location specification; This defaults
+# to <script_location>/versions.  When using multiple version
+# directories, initial revisions must be specified with --version-path.
+# The path separator used here should be the separator specified by "path_separator"
+# below.
+# version_locations = %(here)s/bar:%(here)s/bat:%(here)s/alembic/versions
+
+# path_separator; This indicates what character is used to split lists of file
+# paths, including version_locations and prepend_sys_path within configparser
+# files such as alembic.ini.
+# The default rendered in new alembic.ini files is "os", which uses os.pathsep
+# to provide os-dependent path splitting.
+#
+# Note that in order to support legacy alembic.ini files, this default does NOT
+# take place if path_separator is not present in alembic.ini.  If this
+# option is omitted entirely, fallback logic is as follows:
+#
+# 1. Parsing of the version_locations option falls back to using the legacy
+#    "version_path_separator" key, which if absent then falls back to the legacy
+#    behavior of splitting on spaces and/or commas.
+# 2. Parsing of the prepend_sys_path option falls back to the legacy
+#    behavior of splitting on spaces, commas, or colons.
+#
+# Valid values for path_separator are:
+#
+# path_separator = :
+# path_separator = ;
+# path_separator = space
+# path_separator = newline
+#
+# Use os.pathsep. Default configuration used for new projects.
+path_separator = os
+
+# set to 'true' to search source files recursively
+# in each "version_locations" directory
+# new in Alembic version 1.10
+# recursive_version_locations = false
+
+# the output encoding used when revision files
+# are written from script.py.mako
+# output_encoding = utf-8
+
+# database URL.  This is consumed by the user-maintained env.py script only.
+# other means of configuring database URLs may be customized within the env.py
+# file.
+sqlalchemy.url = {db_url}
+
+# set the version table name
+version_table = migration_version
+
+[post_write_hooks]
+# post_write_hooks defines scripts or Python functions that are run
+# on newly generated revision scripts.  See the documentation for further
+# detail and examples
+
+# format using "black" - use the console_scripts runner, against the "black" entrypoint
+# hooks = black
+# black.type = console_scripts
+# black.entrypoint = black
+# black.options = -l 79 REVISION_SCRIPT_FILENAME
+
+# lint with attempts to fix using "ruff" - use the module runner, against the "ruff" module
+# hooks = ruff
+# ruff.type = module
+# ruff.module = ruff
+# ruff.options = check --fix REVISION_SCRIPT_FILENAME
+
+# Alternatively, use the exec runner to execute a binary found on your PATH
+# hooks = ruff
+# ruff.type = exec
+# ruff.executable = ruff
+# ruff.options = check --fix REVISION_SCRIPT_FILENAME
+
+# Logging configuration.  This is also consumed by the user-maintained
+# env.py script only.
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARNING
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARNING
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S
+"""
+
+
+# ===================== 内部工具 =====================
+
+def _resolve_alembic_config(db_url: str | None = None, project_dir: Path | None = None) -> Config:
+    """构造 Alembic Config 对象，读取项目根目录的 alembic.ini
+
+    Args:
+        db_url: 数据库连接URL（可选，不传则从 alembic.ini 读取）
+        project_dir: 项目根目录（默认当前工作目录）
+
+    Returns:
+        Alembic 配置对象
+
+    Raises:
+        FileNotFoundError: 若根目录 alembic.ini 不存在，提示用户先执行 init
+    """
+    here = project_dir or Path.cwd()
+    root_ini = here / 'alembic.ini'
+
+    if not root_ini.exists():
+        raise FileNotFoundError(
+            f'未找到 {root_ini}，请先执行: fastapi-augment-migrate init --db-url "<数据库URL>"'
+        )
+
+    cfg = Config(str(root_ini))
+    if db_url:
+        cfg.set_main_option('sqlalchemy.url', db_url)
+    return cfg
+
+
+# ===================== init =====================
+
+def init_project(db_url: str, project_dir: Path | None = None) -> None:
+    """初始化项目迁移环境
+
+    在项目根目录生成 alembic.ini 和 alembic/versions/ 目录。
+    若 alembic.ini 已存在则跳过，不覆盖。
+
+    Args:
+        db_url: 数据库连接URL
+        project_dir: 项目根目录
+    """
+    here = project_dir or Path.cwd()
+    alembic_ini = here / 'alembic.ini'
+    versions_dir = here / 'migrations' / 'versions'
+
+    if alembic_ini.exists():
+        _logger.info('%s 已存在，跳过（不会覆盖）', alembic_ini)
+    else:
+        ini_content = _ALEMBIC_INI_TEMPLATE.format(db_url=db_url)
+        alembic_ini.write_text(ini_content)
+        _logger.info('已创建 %s', alembic_ini)
+
+    versions_dir.mkdir(parents=True, exist_ok=True)
+    _logger.info('已确保 %s 存在', versions_dir)
+    _logger.info('初始化完成，现在可以使用 generate 生成迁移了')
+
+
+# ===================== upgrade / downgrade =====================
+
+def upgrade(db_url: str | None = None, revision: str = 'head', project_dir: Path | None = None) -> None:
+    """升级数据库
+
+    Args:
+        db_url: 数据库连接URL（可选，不传则从 alembic.ini 读取）
+        revision: 目标修订版本
+        project_dir: 项目根目录
+    """
+    cfg = _resolve_alembic_config(db_url, project_dir)
+    command.upgrade(cfg, revision)
+
+
+def downgrade(db_url: str | None = None, revision: str = '-1', project_dir: Path | None = None) -> None:
+    """降级数据库
+
+    Args:
+        db_url: 数据库连接URL（可选，不传则从 alembic.ini 读取）
+        revision: 目标修订版本
+        project_dir: 项目根目录
+    """
+    cfg = _resolve_alembic_config(db_url, project_dir)
+    command.downgrade(cfg, revision)
+
+
+# ===================== generate =====================
+
+def generate_migration(message: str, models: str, project_dir: Path | None = None) -> None:
+    """生成迁移文件
+
+    调用 alembic revision --autogenerate 生成迁移脚本。
+    需要项目根目录已存在 alembic.ini（通过 init 命令创建）。
+
+    Args:
+        message: 迁移描述信息
+        models: 模型模块，多个用逗号分隔 (如 myapp.models)
+        project_dir: 项目根目录
+    """
+    here = project_dir or Path.cwd()
+    alembic_ini = here / 'alembic.ini'
+    versions_dir = here / 'migrations' / 'versions'
+
+    # 检查 alembic.ini 是否存在（不自动创建，由 init 负责）
+    if not alembic_ini.exists():
+        raise FileNotFoundError(
+            f'未找到 {alembic_ini}，请先执行: fastapi-augment-migrate init --db-url "<数据库URL>"'
+        )
+
+    # 确保 versions 目录存在
+    versions_dir.mkdir(parents=True, exist_ok=True)
+
+    # 设置环境变量，让库内的 env.py 能加载用户模型
+    env = environ.copy()
+    env['FASTAPI_AUGMENT_MODELS'] = models
+
+    # 先 stamp head，同步数据库版本标记，
+    # 避免 "Target database is not up to date" 错误
+    stamp_cmd = [
+        sys.executable, '-m', 'alembic',
+        '-c', str(alembic_ini),
+        'stamp', 'head'
+    ]
+    subprocess.run(stamp_cmd, env=env, cwd=str(here))
+
+    # 调用 alembic 生成迁移
+    cmd = [
+        sys.executable, '-m', 'alembic',
+        '-c', str(alembic_ini),
+        'revision', '--autogenerate', '-m', message
+    ]
+    try:
+        subprocess.run(cmd, env=env, cwd=str(here), check=True)
+        _logger.info('迁移脚本已生成于 %s', versions_dir)
+    except subprocess.CalledProcessError as e:
+        raise RuntimeError(f'生成迁移失败 (返回码 {e.returncode})') from e
+
+
+# ===================== CLI 入口 =====================
+
+def cli_main() -> None:
+    """数据库迁移工具 (fastapi-augment)"""
+    parser = argparse.ArgumentParser(description='数据库迁移工具 (fastapi-augment)')
+    subparsers = parser.add_subparsers(dest='command', required=True, help='子命令')
+
+    # --- init ---
+    init_parser = subparsers.add_parser('init', help='初始化项目迁移环境')
+    init_parser.add_argument('--db-url', default='sqlite:///app.db', help='数据库连接 URL')
+    init_parser.add_argument('--project-dir', type=Path, default=None, help='项目根目录（默认为当前工作目录）')
+
+    # --- upgrade ---
+    up_parser = subparsers.add_parser('upgrade', help='执行数据库迁移')
+    up_parser.add_argument('--db-url', help='数据库连接 URL（不传则从 alembic.ini 读取）')
+    up_parser.add_argument('--revision', default='head', help='目标版本 (默认: head)')
+    up_parser.add_argument('--downgrade', action='store_true', help='降级而非升级')
+    up_parser.add_argument('--project-dir', type=Path, default=None, help='项目根目录（默认为当前工作目录）')
+
+    # --- generate ---
+    gen_parser = subparsers.add_parser('generate', help='生成迁移脚本')
+    gen_parser.add_argument('--message', required=True, help='迁移描述信息')
+    gen_parser.add_argument('--models', required=True, help='模型模块，多个用逗号分隔 (如 myapp.models)')
+    gen_parser.add_argument('--project-dir', type=Path, default=None, help='项目根目录（默认为当前工作目录）')
+
+    args = parser.parse_args()
+
+    try:
+        if args.command == 'init':
+            init_project(args.db_url, args.project_dir)
+        elif args.command == 'upgrade':
+            if args.downgrade:
+                downgrade(args.db_url, args.revision, args.project_dir)
+            else:
+                upgrade(args.db_url, args.revision, args.project_dir)
+        elif args.command == 'generate':
+            generate_migration(args.message, args.models, args.project_dir)
+        else:
+            parser.print_help()
+    except (FileNotFoundError, RuntimeError) as e:
+        _logger.error('%s', e)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    cli_main()

fastapi_augment/db/sqlalchemy/mixins/__init__.py

@@ -0,0 +1,18 @@
+"""
+@Author         : hangu
+@CreateDate     : 2026/8/31
+@Description    : 通用模型混入类 — 时间戳、软删除、审计，均支持细粒度组合。
+"""
+from .audit import CreatedByMixin, UpdatedByMixin, AuditMixin
+from .soft_delete import SoftDeleteMixin, SoftDeleteAuditMixin
+from .timestamp import CreatedAtMixin, TimestampMixin
+
+__all__ = [
+    'CreatedByMixin',
+    'UpdatedByMixin',
+    'AuditMixin',
+    'SoftDeleteMixin',
+    'SoftDeleteAuditMixin',
+    'CreatedAtMixin',
+    'TimestampMixin',
+]

fastapi_augment/db/sqlalchemy/mixins/audit.py

@@ -0,0 +1,61 @@
+"""
+@Author         : hangu
+@CreateDate     : 2026/9/1
+@Description    : 审计混入类，可整体或细粒度组合 created_by / updated_by 列。
+"""
+from __future__ import annotations
+
+from sqlalchemy import String
+from sqlalchemy.orm import Mapped, mapped_column
+
+
+class CreatedByMixin:
+    """创建人混入类
+
+    仅添加 created_by 一列，记录创建操作人ID，
+    默认对齐 ModelBase 的 ULID 主键长度（String(26)）。
+    """
+
+    created_by: Mapped[str | None] = mapped_column(
+        String(26),
+        default=None,
+        comment='创建人ID',
+        sort_order=901
+    )
+
+
+class UpdatedByMixin:
+    """更新人混入类
+
+    仅添加 updated_by 一列，记录最近更新操作人ID。
+    """
+
+    updated_by: Mapped[str | None] = mapped_column(
+        String(26),
+        default=None,
+        comment='更新人ID',
+        sort_order=911
+    )
+
+
+class AuditMixin(CreatedByMixin, UpdatedByMixin):
+    """审计混入类
+
+    组合 CreatedByMixin + UpdatedByMixin，即常见的
+    created_by / updated_by 成对出现；只要其中一列时，
+    直接继承对应的细粒度混入类::
+
+        class Article(CreatedByMixin, ModelBase):  # 只记录创建人
+            ...
+
+    两列均为可空：系统任务（无登录用户上下文）写入时留空；
+    由 service 层从当前请求上下文取用户ID填充::
+
+        await crud.create(
+            session,
+            User(name='alice', created_by=current_user.id),
+        )
+        await crud.update_by_id(
+            session, uid, updated_by=current_user.id, **changes,
+        )
+    """

fastapi_augment/db/sqlalchemy/mixins/soft_delete.py

@@ -0,0 +1,80 @@
+"""
+@Author         : hangu
+@CreateDate     : 2026/9/1
+@Description    : 软删除混入类，提供 is_deleted / deleted_at 通用列。
+"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import Boolean, DateTime, ColumnExpressionArgument, String
+from sqlalchemy.orm import Mapped, mapped_column
+
+
+class SoftDeleteMixin:
+    """软删除混入类
+
+    为模型添加 is_deleted / deleted_at 两列，配合 CrudBase 使用::
+
+        # 标记删除（service 层负责）
+        await crud.update_by_id(
+            session, uid,
+            is_deleted=True,
+            deleted_at=datetime.now(timezone.utc),
+        )
+
+        # 只查询未删除数据
+        await crud.list(session, expressions=(User.not_deleted(),))
+
+    注意：软删除只是应用层约定，数据库的唯一约束、外键等
+    不会感知软删状态（软删行仍占用唯一键），需在业务层处理。
+    """
+
+    is_deleted: Mapped[bool] = mapped_column(
+        Boolean,
+        default=False,
+        index=True,
+        comment='是否已删除',
+        sort_order=920
+    )
+    deleted_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True),
+        default=None,
+        comment='删除时间',
+        sort_order=921
+    )
+
+    @classmethod
+    def not_deleted(cls) -> ColumnExpressionArgument[bool]:
+        """未删除的过滤条件"""
+        return cls.is_deleted.is_(False)
+
+    @classmethod
+    def only_deleted(cls) -> ColumnExpressionArgument[bool]:
+        """已删除的过滤条件"""
+        return cls.is_deleted.is_(True)
+
+
+class SoftDeleteAuditMixin(SoftDeleteMixin):
+    """带操作人审计的软删除扩展 Mixin
+
+    在基础软删之上增加 deleted_by，记录是谁执行软删除。
+    需要审计删除人的模型再继承本类，不要全局滥用。
+
+    使用示例::
+        await crud.update_by_id(
+            session,
+            uid,
+            is_deleted=True,
+            deleted_at=datetime.now(timezone.utc),
+            deleted_by=operator_user_id,
+        )
+    """
+
+    # 根据你的主键类型调整：ULID / str / int，这里示例用 str，可改成 ULID
+    deleted_by: Mapped[str | None] = mapped_column(
+        String(26),
+        default=None,
+        comment='执行软删除操作人ID',
+        sort_order=922
+    )

fastapi_augment/db/sqlalchemy/mixins/timestamp.py

@@ -0,0 +1,48 @@
+"""
+@Author         : hangu
+@CreateDate     : 2026/9/1
+@Description    : 时间戳混入类，可整体或细粒度组合 created_at / updated_at 列。
+"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import DateTime, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+
+class CreatedAtMixin:
+    """创建时间混入类
+
+    仅添加 created_at 一列，插入时由数据库时钟生成，之后不再变化。
+    适用于只增不改的表（日志、流水、快照等）。
+    """
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        comment='创建时间',
+        sort_order=900
+    )
+
+
+class TimestampMixin(CreatedAtMixin):
+    """时间戳混入类
+
+    继承 CreatedAtMixin ，即常见的
+    created_at / updated_at 成对出现；只要其中一列时，
+    直接继承对应的细粒度混入类::
+
+        class Log(CreatedAtMixin, ModelBase):   # 只要创建时间
+            ...
+
+        class User(TimestampMixin, ModelBase):  # 两列都要
+            ...
+    """
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        onupdate=func.now(),
+        comment='更新时间',
+        sort_order=910
+    )

fastapi_augment/db/sqlalchemy/model_base.py

@@ -0,0 +1,47 @@
+"""
+@Author         : hangu
+@CreateDate     : 2026/8/31
+@Description    : SQLAlchemy 模型基础类
+"""
+from sqlalchemy import String
+from sqlalchemy.orm import Mapped, mapped_column
+from ulid import ULID
+
+from .base import Base
+
+
+def _generate_ulid() -> str:
+    """生成ULID
+
+    Returns:
+        ULID字符串
+    """
+    return str(ULID()).lower()
+
+
+class ModelBase(Base):
+    """SQLAlchemy模型基础类
+
+    仅提供通用的 ULID 主键字段；时间戳、软删除、审计等
+    通用列通过 mixins 按需组合，成对的列可整体使用，
+    也可用细粒度混入类只取其中一列：
+
+        from .mixins import (
+            CreatedAtMixin, SoftDeleteMixin, TimestampMixin,
+        )
+
+        class User(TimestampMixin, SoftDeleteMixin, ModelBase):
+            ...                                             # created_at + updated_at
+
+        class Log(CreatedAtMixin, ModelBase):              # 只要创建时间
+            ...
+    """
+    __abstract__ = True
+
+    id: Mapped[str] = mapped_column(
+        String(26),
+        default=_generate_ulid,
+        primary_key=True,
+        comment='主键ID',
+        sort_order=-1
+    )