fastapi-augment 0.1.3__tar.gz → 0.1.4__tar.gz

{fastapi_augment-0.1.3 → fastapi_augment-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-augment
-Version: 0.1.3
+Version: 0.1.4
 Summary: FastAPI 通用代码工具包，跨项目复用
 Author-email: zarkhan <hanguangzheng@qq.com>
 License-Expression: MIT
@@ -597,12 +597,12 @@ raise BadRequestError(detail='用户名不能为空')
 raise TooManyRequestsError(retry_after=60)
 ```
 
-### 日志管理 — `log`
+### 日志管理 — `logger`
 
 导入即生效：自动注入 `request_id` 到每条日志、接管 uvicorn/fastapi 日志输出。
 
 ```python
-from fastapi_augment.log import setup_logger, set_log_level
+from fastapi_augment.logger import setup_logger, set_log_level
 
 # 一键配置：控制台 + 按天轮转文件日志
 setup_logger(log_dir='./logs', rotation='day', backup_count=30)
@@ -691,26 +691,30 @@ app.include_router(create_health_router(
 
 ### 配置管理 — `config`
 
-基于 `pydantic-settings`，通过 `from_env()` 直接传参，无需手动导入 `SettingsConfigDict`：
+基于 `pydantic-settings`，支持多种配置来源（环境变量、.env、JSON、YAML、TOML），通过不同类方法加载：
 
 ```python
-from fastapi_augment.config import EnvSettings
+from fastapi_augment.config import AugmentBaseSettings
 
-class Settings(EnvSettings):
+class Settings(AugmentBaseSettings):
     database_url: str
     redis_url: str = ''
     debug: bool = False
     secret_key: str = 'change-me'
 
-# 直接传入 .env 路径、前缀等
-settings = Settings.from_env(
-    env_file='config/.env',
-    env_prefix='APP_',
-    env_nested_delimiter='__',
-)
+# 从环境变量加载
+cfg = Settings.from_env(env_prefix='APP_', env_nested_delimiter='__')
+
+# 从 .env 文件加载
+cfg = Settings.from_dotenv('.env', env_prefix='APP_')
+
+# 从 JSON / YAML / TOML 文件加载
+cfg = Settings.from_json('config.json')
+cfg = Settings.from_yaml('config.yaml')
+cfg = Settings.from_toml('config.toml')
 ```
 
-支持 `SettingsConfigDict` 的所有参数（`env_file`、`env_prefix`、`secrets_dir`、`yaml_file` 等），
+支持 `SettingsConfigDict` 的所有参数（`env_prefix`、`secrets_dir`、`yaml_file` 等），
 与模型字段值自动区分，无需关心分类。
 
 ### 中间件 — `middlewares`
@@ -736,7 +740,8 @@ fastapi_augment/
 │   └── utils/
 │       └── strings.py        # 字符串工具 / JSON 序列化
 ├── config/
-│   └── settings.py           # EnvSettings 配置管理
+│   ├── base_settings.py       # AugmentBaseSettings 配置管理
+│   └── database_settings.py   # DatabaseSettings 数据库配置
 ├── db/
 │   └── sqlalchemy/
 │       ├── engine.py         # EngineManager / NodeConfig / ClusterTopology
@@ -751,11 +756,11 @@ fastapi_augment/
 │   ├── checker.py            # BaseChecker / CheckResult / HealthResponse
 │   ├── checkers.py           # AppChecker / DatabaseChecker
 │   └── router.py             # create_health_router()
-├── log/
-│   ├── factory.py            # request_id 注入工厂
+├── logger/
+│   ├── record_factory.py     # request_id 注入工厂
 │   ├── filters.py            # UvicornNameRewriteFilter
 │   ├── handlers.py           # 多进程安全轮转处理器
-│   └── config.py             # setup_logger / set_log_level / set_log_format
+│   └── setup.py              # setup_logger / set_log_level / set_log_format
 ├── middlewares/
 │   ├── base.py               # BaseASGIMiddleware
 │   └── request_id.py         # RequestId 中间件

{fastapi_augment-0.1.3 → fastapi_augment-0.1.4}/README.md

@@ -560,12 +560,12 @@ raise BadRequestError(detail='用户名不能为空')
 raise TooManyRequestsError(retry_after=60)
 ```
 
-### 日志管理 — `log`
+### 日志管理 — `logger`
 
 导入即生效：自动注入 `request_id` 到每条日志、接管 uvicorn/fastapi 日志输出。
 
 ```python
-from fastapi_augment.log import setup_logger, set_log_level
+from fastapi_augment.logger import setup_logger, set_log_level
 
 # 一键配置：控制台 + 按天轮转文件日志
 setup_logger(log_dir='./logs', rotation='day', backup_count=30)
@@ -654,26 +654,30 @@ app.include_router(create_health_router(
 
 ### 配置管理 — `config`
 
-基于 `pydantic-settings`，通过 `from_env()` 直接传参，无需手动导入 `SettingsConfigDict`：
+基于 `pydantic-settings`，支持多种配置来源（环境变量、.env、JSON、YAML、TOML），通过不同类方法加载：
 
 ```python
-from fastapi_augment.config import EnvSettings
+from fastapi_augment.config import AugmentBaseSettings
 
-class Settings(EnvSettings):
+class Settings(AugmentBaseSettings):
     database_url: str
     redis_url: str = ''
     debug: bool = False
     secret_key: str = 'change-me'
 
-# 直接传入 .env 路径、前缀等
-settings = Settings.from_env(
-    env_file='config/.env',
-    env_prefix='APP_',
-    env_nested_delimiter='__',
-)
+# 从环境变量加载
+cfg = Settings.from_env(env_prefix='APP_', env_nested_delimiter='__')
+
+# 从 .env 文件加载
+cfg = Settings.from_dotenv('.env', env_prefix='APP_')
+
+# 从 JSON / YAML / TOML 文件加载
+cfg = Settings.from_json('config.json')
+cfg = Settings.from_yaml('config.yaml')
+cfg = Settings.from_toml('config.toml')
 ```
 
-支持 `SettingsConfigDict` 的所有参数（`env_file`、`env_prefix`、`secrets_dir`、`yaml_file` 等），
+支持 `SettingsConfigDict` 的所有参数（`env_prefix`、`secrets_dir`、`yaml_file` 等），
 与模型字段值自动区分，无需关心分类。
 
 ### 中间件 — `middlewares`
@@ -699,7 +703,8 @@ fastapi_augment/
 │   └── utils/
 │       └── strings.py        # 字符串工具 / JSON 序列化
 ├── config/
-│   └── settings.py           # EnvSettings 配置管理
+│   ├── base_settings.py       # AugmentBaseSettings 配置管理
+│   └── database_settings.py   # DatabaseSettings 数据库配置
 ├── db/
 │   └── sqlalchemy/
 │       ├── engine.py         # EngineManager / NodeConfig / ClusterTopology
@@ -714,11 +719,11 @@ fastapi_augment/
 │   ├── checker.py            # BaseChecker / CheckResult / HealthResponse
 │   ├── checkers.py           # AppChecker / DatabaseChecker
 │   └── router.py             # create_health_router()
-├── log/
-│   ├── factory.py            # request_id 注入工厂
+├── logger/
+│   ├── record_factory.py     # request_id 注入工厂
 │   ├── filters.py            # UvicornNameRewriteFilter
 │   ├── handlers.py           # 多进程安全轮转处理器
-│   └── config.py             # setup_logger / set_log_level / set_log_format
+│   └── setup.py              # setup_logger / set_log_level / set_log_format
 ├── middlewares/
 │   ├── base.py               # BaseASGIMiddleware
 │   └── request_id.py         # RequestId 中间件

fastapi_augment-0.1.4/VERSION

@@ -0,0 +1 @@
+0.1.4

{fastapi_augment-0.1.3 → fastapi_augment-0.1.4}/src/fastapi_augment/common/constants.py

@@ -1,7 +1,7 @@
 """
 @Author         : hangu
 @CreateDate     : 2026/9/4
-@Description    :
+@Description    : 全局常量与统一默认错误文案
 """
 from starlette import status
 
@@ -21,6 +21,7 @@ DEFAULT_ERR_MSG: dict[int, str] = {
     status.HTTP_413_CONTENT_TOO_LARGE: 'Payload too large',
     status.HTTP_414_URI_TOO_LONG: 'URI too long',
     status.HTTP_415_UNSUPPORTED_MEDIA_TYPE: 'Unsupported media type',
+    status.HTTP_422_UNPROCESSABLE_CONTENT: 'Unprocessable entity',
     status.HTTP_423_LOCKED: 'Locked',
     status.HTTP_429_TOO_MANY_REQUESTS: 'Too many requests',
 }

{fastapi_augment-0.1.3 → fastapi_augment-0.1.4}/src/fastapi_augment/common/exception_handlers.py

@@ -27,11 +27,11 @@ async def base_http_error_handler(
         _request: Request,
         exc: BaseHttpError,
 ) -> JSONResponse:
-    """处理 BaseHttpError 及其所有子类（统一业务异常）。
+    """处理 BaseHttpError 及其所有子类（统一业务异常）
 
     将业务异常转换为统一 APIResponse 格式，
     HTTP 状态码与 exc.status_code 一致，
-    body.code 同样使用 HTTP 状态码，body.message 使用 exc.detail。
+    body.code 同样使用 HTTP 状态码，body.message 使用 exc.detail
 
     Args:
         _request: Starlette Request 对象
@@ -54,11 +54,11 @@ async def http_exception_handler(
         _request: Request,
         exc: HTTPException,
 ) -> JSONResponse:
-    """处理 Starlette/FastAPI 原生 HTTPException。
+    """处理 Starlette/FastAPI 原生 HTTPException
 
-    覆盖 FastAPI 默认处理器，将响应格式统一为 APIResponse。
+    覆盖 FastAPI 默认处理器，将响应格式统一为 APIResponse
     注意：BaseHttpError 继承自 HTTPException，但 FastAPI 会优先匹配
-    更具体的处理器（base_http_error_handler），所以此处不会拦截业务异常。
+    更具体的处理器（base_http_error_handler），所以此处不会拦截业务异常
 
     Args:
         _request: Starlette Request 对象
@@ -84,9 +84,9 @@ async def validation_exception_handler(
         _request: Request,
         exc: RequestValidationError,
 ) -> JSONResponse:
-    """处理 Pydantic 请求参数校验异常（422）。
+    """处理 Pydantic 请求参数校验异常（422）
 
-    将校验错误详情提取到 extra.errors 中，方便前端定位具体字段。
+    将校验错误详情提取到 extra.errors 中，方便前端定位具体字段
 
     Args:
         _request: Starlette Request 对象
@@ -121,10 +121,10 @@ async def general_exception_handler(
         _request: Request,
         exc: Exception,
 ) -> JSONResponse:
-    """处理所有未被捕获的异常（兜底）。
+    """处理所有未被捕获的异常（兜底）
 
     记录完整异常日志（含堆栈），但响应体只返回通用提示，
-    避免将内部实现细节（堆栈、SQL 等）暴露给客户端。
+    避免将内部实现细节（堆栈、SQL 等）暴露给客户端
 
     Args:
         _request: Starlette Request 对象
@@ -144,7 +144,7 @@ async def general_exception_handler(
 # ===================== 一键注册 =====================
 
 def register_exception_handlers(app: FastAPI) -> None:
-    """将全部统一异常处理器注册到 FastAPI 应用。
+    """将全部统一异常处理器注册到 FastAPI 应用
 
     注册后，以下异常会被转换为统一的 APIResponse 格式：
         - BaseHttpError 及子类 → 对应 HTTP 状态码

{fastapi_augment-0.1.3 → fastapi_augment-0.1.4}/src/fastapi_augment/common/exceptions.py

@@ -13,7 +13,7 @@ from .constants import DEFAULT_ERR_MSG
 
 # ===================== 通用基类：统一封装 detail + headers 逻辑 =====================
 class BaseHttpError(HTTPException):
-    """统一HTTP异常基类，所有4xx异常继承此类，原生兼容starlette.HTTPException.
+    """统一HTTP异常基类，所有4xx异常继承此类，原生兼容starlette.HTTPException
 
     子类只需声明 ``_status_code`` 类变量，无需重写 __init__::
 
@@ -38,7 +38,7 @@ class BaseHttpError(HTTPException):
             detail: str | None = None,
             headers: dict[str, Any] | None = None,
     ):
-        """初始化http业务异常.
+        """初始化http业务异常
 
         Args:
             status_code: http响应状态码，不传则读取子类的 _status_code 类变量
@@ -62,82 +62,82 @@ class BaseHttpError(HTTPException):
 # ===================== 各类4xx异常子类（极简声明，无重复__init__） =====================
 # 子类只需声明 _status_code 类变量，__init__ 由基类统一处理
 class BadRequestError(BaseHttpError):
-    """400 请求错误."""
+    """400 请求错误"""
     _status_code = status.HTTP_400_BAD_REQUEST
 
 
 class UnauthorizedError(BaseHttpError):
-    """401 未授权错误."""
+    """401 未授权错误"""
     _status_code = status.HTTP_401_UNAUTHORIZED
 
 
 class PaymentRequiredError(BaseHttpError):
-    """402 需要付费错误."""
+    """402 需要付费错误"""
     _status_code = status.HTTP_402_PAYMENT_REQUIRED
 
 
 class ForbiddenError(BaseHttpError):
-    """403 禁止访问错误."""
+    """403 禁止访问错误"""
     _status_code = status.HTTP_403_FORBIDDEN
 
 
 class NotFoundError(BaseHttpError):
-    """404 未找到资源."""
+    """404 未找到资源"""
     _status_code = status.HTTP_404_NOT_FOUND
 
 
 class MethodNotAllowedError(BaseHttpError):
-    """405 请求方法不允许."""
+    """405 请求方法不允许"""
     _status_code = status.HTTP_405_METHOD_NOT_ALLOWED
 
 
 class NotAcceptableError(BaseHttpError):
-    """406 客户端不支持返回格式."""
+    """406 客户端不支持返回格式"""
     _status_code = status.HTTP_406_NOT_ACCEPTABLE
 
 
 class RequestTimeoutError(BaseHttpError):
-    """408 请求超时."""
+    """408 请求超时"""
     _status_code = status.HTTP_408_REQUEST_TIMEOUT
 
 
 class ConflictError(BaseHttpError):
-    """409 资源冲突."""
+    """409 资源冲突"""
     _status_code = status.HTTP_409_CONFLICT
 
 
 class GoneError(BaseHttpError):
-    """410 资源已永久删除."""
+    """410 资源已永久删除"""
     _status_code = status.HTTP_410_GONE
 
 
 class PreconditionFailedError(BaseHttpError):
-    """412 前置校验失败."""
+    """412 前置校验失败"""
     _status_code = status.HTTP_412_PRECONDITION_FAILED
 
 
 class PayloadTooLargeError(BaseHttpError):
-    """413 请求体过大."""
+    """413 请求体过大"""
     _status_code = status.HTTP_413_CONTENT_TOO_LARGE
 
 
 class URITooLongError(BaseHttpError):
-    """414 URI链接过长."""
+    """414 URI链接过长"""
     _status_code = status.HTTP_414_URI_TOO_LONG
 
 
 class UnsupportedMediaTypeError(BaseHttpError):
-    """415 不支持的请求媒体类型."""
+    """415 不支持的请求媒体类型"""
     _status_code = status.HTTP_415_UNSUPPORTED_MEDIA_TYPE
 
 
 class LockedError(BaseHttpError):
-    """423 资源锁定."""
+    """423 资源锁定"""
     _status_code = status.HTTP_423_LOCKED
 
 
 class TooManyRequestsError(BaseHttpError):
-    """429 请求过于频繁（限流专用，支持retry_after快捷参数）."""
+    """429 请求过于频繁（限流专用，支持retry_after快捷参数）"""
     _status_code = status.HTTP_429_TOO_MANY_REQUESTS
 
     def __init__(

{fastapi_augment-0.1.3 → fastapi_augment-0.1.4}/src/fastapi_augment/common/utils/__init__.py

@@ -1,7 +1,7 @@
 """
 @Author         : hangu
 @CreateDate     : 2026/9/4
-@Description    :
+@Description    : 通用工具函数（路径、字符串、JSON 序列化）
 """
 from .paths import get_root_dir
 from .strings import (

{fastapi_augment-0.1.3 → fastapi_augment-0.1.4}/src/fastapi_augment/common/utils/paths.py

@@ -1,7 +1,7 @@
 """
 @Author         : hangu
 @CreateDate     : 2026/9/9
-@Description    :
+@Description    : 项目路径工具函数
 """
 import sys
 from pathlib import Path
@@ -10,10 +10,10 @@ from pathlib import Path
 # 获取项目根目录路径
 def get_root_dir(reference_path: str | Path, parent_index: int) -> Path:
     """
-    动态获取项目根目录路径，兼容源码开发环境与 PyInstaller/Nuitka 打包二进制环境。
+    动态获取项目根目录路径，兼容源码开发环境与 PyInstaller/Nuitka 打包二进制环境
 
     源码模式：以传入的参考路径为基准，向上回溯 parent_index 层目录得到项目根；
-    打包 frozen 模式：自动返回可执行文件(.exe/二进制)所在目录，忽略 reference_path、parent_index。
+    打包 frozen 模式：自动返回可执行文件(.exe/二进制)所在目录，忽略 reference_path、parent_index
 
     Args:
         reference_path: 锚点参考路径，业务调用一般直接传入 __file__

{fastapi_augment-0.1.3 → fastapi_augment-0.1.4}/src/fastapi_augment/common/utils/strings.py

@@ -1,7 +1,7 @@
 """
 @Author         : hangu
 @CreateDate     : 2026/9/4
-@Description    :
+@Description    : 字符串工具函数——命名转换、随机串、JSON 序列化
 """
 import json
 import random
@@ -40,7 +40,11 @@ _ORJSON_OPT_INDENT_2 = 0x04
 
 # ── 字符串转换 ──
 def camel_to_snake(s: str) -> str:
-    """驼峰转下划线（支持连续大写）"""
+    """驼峰转下划线（支持连续大写）
+
+    Returns:
+        转换后的下划线命名字符串
+    """
     if not s:
         return s
     result: list[str] = []
@@ -58,7 +62,11 @@ def camel_to_snake(s: str) -> str:
 
 
 def snake_to_camel(s: str) -> str:
-    """下划线转驼峰（首字母大写）"""
+    """下划线转驼峰（首字母大写）
+
+    Returns:
+        转换后的驼峰命名字符串
+    """
     if not s:
         return s
     return ''.join(part.capitalize() for part in s.split('_'))
@@ -72,9 +80,14 @@ def random_string(
 ) -> str:
     """生成随机字符串，支持自定义字符集
 
+    Returns:
+        指定长度的随机字符串
+
     Raises:
-        ValueError: 字符集为空时（exclude 排除了所有字符）
+        ValueError: length 非正整数或字符集为空时（exclude 排除了所有字符）
     """
+    if length < 1:
+        raise ValueError(f'length 必须为正整数，当前值: {length}')
     if chars is None:
         chars = string.ascii_letters + string.digits
     if exclude:

fastapi_augment-0.1.4/src/fastapi_augment/config/__init__.py

@@ -0,0 +1,12 @@
+"""
+@Author         : zarkhan
+@CreateDate     : 2026/9/6
+@Description    : 配置管理模块
+"""
+from .base_settings import AugmentBaseSettings
+from .database_settings import DatabaseSettings
+
+__all__ = [
+    'AugmentBaseSettings',
+    'DatabaseSettings'
+]