fastapi-augment 0.1.0__py3-none-any.whl

fastapi_augment/config/settings.py

@@ -0,0 +1,104 @@
+"""
+@Author     : zarkhan
+@CreateDate : 2026/9/6
+@Description: 基于 pydantic-settings 的环境配置管理
+              - 支持 .env 文件加载（路径由使用者显式指定）
+              - 支持环境变量前缀
+              - 支持嵌套配置（通过分隔符）
+"""
+from __future__ import annotations
+
+from typing import Any, TypeVar
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+# SettingsConfigDict 所有可用键，用于区分配置参数和模型字段值
+_CONFIG_KEYS = frozenset(SettingsConfigDict.__annotations__.keys())
+
+_S = TypeVar('_S', bound='EnvSettings')
+
+
+class EnvSettings(BaseSettings):
+    """环境配置基类，继承 pydantic_settings.BaseSettings。
+
+    自动从环境变量和 ``.env`` 文件加载配置，通过 ``from_env()`` 直接传参::
+
+        from fastapi_augment.config import EnvSettings
+
+        class Settings(EnvSettings):
+            database_url: str
+            redis_url: str = ''
+            debug: bool = False
+
+        # 直接传入 .env 路径、前缀等，无需导入 SettingsConfigDict
+        settings = Settings.from_env(
+            env_file='config/.env',
+            env_prefix='APP_',
+        )
+
+    特性：
+        - ``.env`` 文件路径由使用者显式指定，库不猜测项目根目录
+        - 支持 ``env_prefix`` 前缀过滤（如 ``APP_`` → ``APP_DATABASE_URL``）
+        - 支持 ``env_nested_delimiter`` 嵌套配置（如 ``DB__URL=xxx``）
+        - 环境变量优先级高于 .env 文件
+        - 默认 ``extra='ignore'``，未声明的环境变量被安全忽略
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix='',
+        env_file=None,
+        env_nested_delimiter=None,
+        case_sensitive=False,
+        extra='ignore',
+    )
+
+    @classmethod
+    def from_env(cls: type[_S], **kwargs: Any) -> _S:
+        """从环境加载配置，支持 ``SettingsConfigDict`` 所有参数。
+
+        内部自动区分 ``SettingsConfigDict`` 配置参数和模型字段值：
+        - 属于 ``SettingsConfigDict`` 的键 → 覆盖 ``model_config``
+        - 其余键 → 直接覆盖模型字段值（优先级最高）
+
+        常用配置参数：
+            env_file: .env 文件路径
+            env_prefix: 环境变量前缀（如 ``'APP_'``）
+            env_nested_delimiter: 嵌套配置分隔符（如 ``'__'``）
+            case_sensitive: 环境变量大小写敏感
+            env_file_encoding: .env 文件编码
+            secrets_dir: secrets 目录路径
+            json_file: JSON 配置文件路径
+            yaml_file: YAML 配置文件路径
+            toml_file: TOML 配置文件路径
+            cli_parse_args: 是否解析命令行参数
+
+        Returns:
+            配置实例
+
+        Example::
+
+            settings = Settings.from_env(
+                env_file='config/.env',
+                env_prefix='APP_',
+                env_nested_delimiter='__',
+                debug=True,               # 模型字段值覆盖
+            )
+        """
+        config_overrides: dict[str, Any] = {}
+        field_overrides: dict[str, Any] = {}
+
+        for key, value in kwargs.items():
+            if key in _CONFIG_KEYS:
+                config_overrides[key] = str(value) if key == 'env_file' and value is not None else value
+            else:
+                field_overrides[key] = value
+
+        if config_overrides:
+            sub_cls = type(
+                f'{cls.__name__}__env',
+                (cls,),
+                {'model_config': SettingsConfigDict(**{**dict(cls.model_config), **config_overrides})},
+            )
+            return sub_cls(**field_overrides)
+
+        return cls(**field_overrides)

fastapi_augment/db/__init__.py

@@ -0,0 +1,5 @@
+"""
+@Author         : hangu
+@CreateDate     : 2026/8/31
+@Description    :
+"""

fastapi_augment/db/sqlalchemy/__init__.py

@@ -0,0 +1,20 @@
+"""
+@Author         : hangu
+@CreateDate     : 2026/8/31
+@Description    : SQLAlchemy integration — engine, session, model base, mixins, and CRUD base.
+"""
+from .base import Base
+from .crud_base import CrudBase
+from .engine import ClusterTopology, EngineManager, NodeConfig
+from .model_base import ModelBase
+from .session import SessionFactory
+
+__all__ = [
+    'Base',
+    'CrudBase',
+    'ClusterTopology',
+    'EngineManager',
+    'NodeConfig',
+    'ModelBase',
+    'SessionFactory'
+]

fastapi_augment/db/sqlalchemy/alembic/__init__.py

@@ -0,0 +1,5 @@
+"""
+@Author     : zarkhan
+@CreateDate : 2026/9/5
+@Description: 
+"""

fastapi_augment/db/sqlalchemy/alembic/env.py

@@ -0,0 +1,141 @@
+import asyncio
+import importlib
+from logging import getLogger
+from logging.config import fileConfig
+from os import environ
+from urllib.parse import urlparse
+
+from alembic import context
+from sqlalchemy import Connection, pool, engine_from_config
+from sqlalchemy.ext.asyncio import async_engine_from_config
+
+from fastapi_augment.db.sqlalchemy import Base
+
+_logger = getLogger(__name__)
+
+# this is the Alembic Config object, which provides
+# access to the values within the .ini file in use.
+config = context.config
+
+# 从 alembic.ini 读取自定义版本表名称，如果没有则使用默认名
+version_table = config.get_main_option('version_table', 'migration_version')
+
+# Interpret the config file for Python logging.
+# This line sets up loggers basically.
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+# add your model's MetaData object here
+# for 'autogenerate' support
+# from myapp import mymodel
+# target_metadata = mymodel.Base.metadata
+
+# 从环境变量 FASTAPI_AUGMENT_MODELS 动态导入用户模型模块，
+# 使模型注册到 Base.metadata，autogenerate 才能检测到变更。
+_models_env = environ.get('FASTAPI_AUGMENT_MODELS', '')
+if _models_env:
+    for _mod in _models_env.split(','):
+        _mod = _mod.strip()
+        if _mod:
+            try:
+                importlib.import_module(_mod)
+            except ImportError as _e:
+                _logger.warning('无法导入模型模块 %s: %s', _mod, _e)
+
+target_metadata = Base.metadata
+
+
+# other values from the config, defined by the needs of env.py,
+# can be acquired:
+# my_important_option = config.get_main_option("my_important_option")
+# ... etc.
+
+
+def run_migrations_offline() -> None:
+    """Run alembic in 'offline' mode.
+
+    This configures the context with just a URL
+    and not an Engine, though an Engine is acceptable
+    here as well.  By skipping the Engine creation
+    we don't even need a DBAPI to be available.
+
+    Calls to context.execute() here emit the given string to the
+    script output.
+
+    """
+    url = config.get_main_option('sqlalchemy.url')
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={'paramstyle': 'named'},
+        version_table=version_table,
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def do_run_migrations(connection: Connection) -> None:
+    """内部实际执行迁移的函数
+
+    Args:
+        connection: SQLAlchemy 数据库连接对象
+    """
+    context.configure(
+        connection=connection,
+        target_metadata=target_metadata,
+        version_table=version_table
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def run_async_migrations() -> None:
+    """异步模式运行迁移
+
+    创建异步引擎并关联连接至上下文
+    """
+    connectable = async_engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix='sqlalchemy.',
+        poolclass=pool.NullPool,
+    )
+
+    async with connectable.connect() as connection:
+        await connection.run_sync(do_run_migrations)
+
+    await connectable.dispose()
+
+
+def run_migrations_online() -> None:
+    """Run alembic in 'online' mode.
+
+    In this scenario we need to create an Engine
+    and associate a connection with the context.
+
+    """
+    url = config.get_main_option('sqlalchemy.url')
+    if not url:
+        raise ValueError('SQLAlchemy URL 未设置')
+
+    async_drivers = {'asyncpg', 'asyncmy', 'aiomysql', 'aiosqlite', 'aioodbc'}
+    is_async = urlparse(url).scheme.split('+')[-1] in async_drivers
+
+    if is_async:
+        asyncio.run(run_async_migrations())
+    else:
+        connectable = engine_from_config(
+            config.get_section(config.config_ini_section, {}),
+            prefix='sqlalchemy.',
+            poolclass=pool.NullPool,
+        )
+        with connectable.connect() as connection:
+            do_run_migrations(connection)
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

fastapi_augment/db/sqlalchemy/base.py

@@ -0,0 +1,9 @@
+"""
+@Author         : hangu
+@CreateDate     : 2026/8/31
+@Description    : SQLAlchemy Base
+"""
+from sqlalchemy.orm import DeclarativeBase
+
+
+class Base(DeclarativeBase): ...