aury-boot 0.0.33__tar.gz → 0.0.35__tar.gz

{aury_boot-0.0.33 → aury_boot-0.0.35}/PKG-INFO

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

{aury_boot-0.0.33 → aury_boot-0.0.35}/aury/boot/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.0.33'
-__version_tuple__ = version_tuple = (0, 0, 33)
+__version__ = version = '0.0.35'
+__version_tuple__ = version_tuple = (0, 0, 35)
 
 __commit_id__ = commit_id = None

{aury_boot-0.0.33 → aury_boot-0.0.35}/aury/boot/application/app/base.py

@@ -280,7 +280,7 @@ class FoundationApp(FastAPI):
         title: str = "Aury Service",
         version: str = "1.0.0",
         description: str | None = None,
-        intercept_loggers: list[str] | None = None,
+        logger_levels: list[tuple[str, str]] | None = None,
         **kwargs: Any,
     ) -> None:
         """初始化应用。
@@ -290,9 +290,8 @@ class FoundationApp(FastAPI):
             title: 应用标题
             version: 应用版本
             description: 应用描述
-            intercept_loggers: 额外需要拦截的标准 logging logger 名称列表，
-                会追加到框架默认列表 (uvicorn, sqlalchemy.engine 等)。
-                也可通过配置 LOG__INTERCEPT_LOGGERS 设置。
+            logger_levels: 需要设置特定级别的 logger 列表，格式: [("name", "LEVEL"), ...]
+                例如: [("sse_starlette", "WARNING"), ("httpx", "INFO")]
             **kwargs: 传递给 FastAPI 的其他参数
         """
         # 加载配置
@@ -304,11 +303,6 @@ class FoundationApp(FastAPI):
         frame = sys._getframe(1)
         self._caller_module = frame.f_globals.get("__name__", "__main__")
 
-        # 合并 intercept_loggers：参数 + 配置
-        merged_intercept = list(config.log.intercept_loggers)
-        if intercept_loggers:
-            merged_intercept.extend(intercept_loggers)
-
         # 初始化日志（必须在其他操作之前）
         setup_logging(
             log_level=config.log.level,
@@ -318,7 +312,7 @@ class FoundationApp(FastAPI):
             retention_days=config.log.retention_days,
             enable_file_rotation=config.log.enable_file_rotation,
             enable_console=config.log.enable_console,
-            intercept_loggers=merged_intercept,
+            logger_levels=logger_levels,
         )
         
         # 注册 access 日志（HTTP 请求日志）

{aury_boot-0.0.33 → aury_boot-0.0.35}/aury/boot/application/config/settings.py

@@ -401,14 +401,6 @@ class LogSettings(BaseModel):
         default=False,
         description="是否记录 WebSocket 消息内容（注意性能和敏感数据）"
     )
-    intercept_loggers: list[str] = Field(
-        default_factory=list,
-        description=(
-            "额外需要由 loguru 接管的标准 logging logger 名称列表。"
-            "框架默认已拦截 uvicorn、uvicorn.error、uvicorn.access、sqlalchemy.engine，"
-            "此处配置会追加到默认列表。"
-        ),
-    )
 
 
 class ServiceSettings(BaseModel):

{aury_boot-0.0.33 → aury_boot-0.0.35}/aury/boot/commands/scheduler.py

@@ -84,9 +84,12 @@ def run_scheduler(
         module = __import__(module_path, fromlist=[app_name])
         application = getattr(module, app_name)
 
-        # 设置日志上下文
-        from aury.boot.common.logging import set_service_context
-        set_service_context("scheduler")
+        # 设置日志（必须在其他操作之前）
+        from aury.boot.common.logging import setup_logging
+        setup_logging(
+            log_level=getattr(application, "_config", None) and application._config.log.level or "INFO",
+            service_type="scheduler",
+        )
 
         # 获取调度器
         from aury.boot.infrastructure.scheduler import SchedulerManager

{aury_boot-0.0.33 → aury_boot-0.0.35}/aury/boot/commands/templates/generate/repository.py.tpl

@@ -11,8 +11,9 @@ class {class_name}Repository(BaseRepository[{class_name}]):
     继承 BaseRepository 自动获得：
     - get(id): 按 ID 获取
     - get_by(**filters): 按条件获取单个
-    - list(skip, limit, **filters): 获取列表
-    - paginate(params, **filters): 分页获取
+    - list(skip, limit, sort, **filters): 获取列表
+    - paginate(pagination, sort, **filters): 分页获取
+    - stream(batch_size, sort, **filters): 流式查询
     - create(data): 创建
     - update(entity, data): 更新
     - delete(entity, soft=True): 删除

{aury_boot-0.0.33 → aury_boot-0.0.35}/aury/boot/commands/templates/project/aury_docs/02-repository.md.tpl

@@ -5,7 +5,7 @@
 **文件**: `{package_name}/repositories/user_repository.py`
 
 ```python
-"""User 数据访问层。"""
+"""“User 数据访问层。"""
 
 from aury.boot.domain.repository.impl import BaseRepository
 
@@ -18,13 +18,14 @@ class UserRepository(BaseRepository[User]):
     继承 BaseRepository 自动获得：
     - get(id): 按 ID 获取
     - get_by(**filters): 按条件获取单个
-    - list(skip, limit, **filters): 获取列表
-    - paginate(params, **filters): 分页获取
+    - list(skip, limit, sort, **filters): 获取列表
+    - paginate(pagination, sort, **filters): 分页获取
     - count(**filters): 计数
     - exists(**filters): 是否存在
     - create(data): 创建
     - update(entity, data): 更新
     - delete(entity, soft=True): 删除（默认软删除）
+    - stream(batch_size, sort, **filters): 流式查询
     - batch_create(data_list): 批量创建
     - bulk_insert(data_list): 高性能批量插入
     """
@@ -35,7 +36,7 @@ class UserRepository(BaseRepository[User]):
 
     async def list_active(self, skip: int = 0, limit: int = 100) -> list[User]:
         """获取激活用户列表。"""
-        return await self.list(skip=skip, limit=limit, is_active=True)
+        return await self.list(skip=skip, limit=limit, sort="-created_at", is_active=True)
 ```
 
 ## 2.2 BaseRepository 方法详解
@@ -50,25 +51,36 @@ repo = UserRepository(session, User)
 user = await repo.get(user_id)                    # 按 ID（支持 int/UUID）
 user = await repo.get_by(email="a@b.com")         # 按条件（简单 AND 过滤）
 users = await repo.list(skip=0, limit=10)         # 列表
+users = await repo.list(sort="-created_at")       # 带排序
 users = await repo.list(is_active=True)           # 带过滤
 count = await repo.count(is_active=True)          # 计数
 exists = await repo.exists(email="a@b.com")       # 是否存在
 
 # === 分页 ===
-from aury.boot.domain.pagination import PaginationParams, SortParams
+from aury.boot.domain.pagination import PaginationParams
 
+# 方式1: offset/limit（与 SQL 语义一致）
 result = await repo.paginate(
-    pagination_params=PaginationParams(page=1, page_size=20),
-    sort_params=SortParams.from_string("-created_at"),
+    pagination=PaginationParams(offset=0, limit=20),
+    sort="-created_at",
+    is_active=True,
+)
+
+# 方式2: page/size（UI 风格）
+result = await repo.paginate(
+    pagination=PaginationParams.of(page=1, size=20),
+    sort="-created_at",
     is_active=True,
 )
 
 # PaginationResult 结构：
 # - result.items: list[T]      # 数据列表
 # - result.total: int          # 总记录数
-# - result.page: int           # 当前页码
-# - result.page_size: int      # 每页数量
-# - result.total_pages: int    # 总页数
+# - result.offset: int         # 当前偏移量
+# - result.limit: int          # 每页数量
+# - result.page: int           # 当前页码（计算属性）
+# - result.size: int           # limit 别名
+# - result.total_pages: int    # 总页数（计算属性）
 # - result.has_next: bool      # 是否有下一页
 # - result.has_prev: bool      # 是否有上一页
 
@@ -96,11 +108,11 @@ result = await repo.cursor_paginate(
 
 # === 流式查询（大数据处理） ===
 # 逐条流式处理，不会一次性加载到内存
-async for user in repo.stream(batch_size=1000, is_active=True):
+async for user in repo.stream(batch_size=1000, sort="-created_at", is_active=True):
     await process(user)
 
 # 批量流式处理
-async for batch in repo.stream_batches(batch_size=1000):
+async for batch in repo.stream_batches(batch_size=1000, sort="id"):
     await bulk_sync_to_es(batch)
 
 # === 创建 ===
@@ -140,27 +152,28 @@ user = await repo.get_by(status__ne="archived")
 
 > 注意：filters 条件之间用 AND 组合；如需 AND/OR/NOT 的复杂组合，请使用 `QueryBuilder`（见 2.4）。
 
-### 2.2.2 排序参数（SortParams）
+### 2.2.2 排序参数（sort）
 
-`SortParams.from_string()` 支持两种语法：
+所有查询方法的 `sort` 参数支持多种格式：
 
 ```python
-from aury.boot.domain.pagination import SortParams
+# 字符串（推荐）
+await repo.list(sort="-created_at")                    # 简洁语法
+await repo.list(sort="-created_at,priority")           # 多字段
+await repo.list(sort="created_at:desc,priority:asc")  # 完整语法
 
-# 简洁语法："-" 前缀表示降序
-sort_params = SortParams.from_string("-created_at")
-sort_params = SortParams.from_string("-created_at,priority")  # 多字段
+# 字符串列表
+await repo.list(sort=["-created_at", "name"])
 
-# 完整语法：字段:方向
-sort_params = SortParams.from_string("created_at:desc,priority:asc")
+# SortParams 对象（需要白名单验证时）
+from aury.boot.domain.pagination import SortParams
 
-# 带字段白名单验证（防止 SQL 注入）
 ALLOWED_FIELDS = {{"id", "created_at", "priority", "status"}}
 sort_params = SortParams.from_string(
     "-created_at",
-    allowed_fields=ALLOWED_FIELDS
+    allowed_fields=ALLOWED_FIELDS  # 传入非法字段抛 ValueError
 )
-# 传入非法字段会抛出 ValueError
+await repo.list(sort=sort_params)
 ```
 
 ### 2.2.3 查询全部（limit=None）

{aury_boot-0.0.33 → aury_boot-0.0.35}/aury/boot/commands/templates/project/main.py.tpl

@@ -25,15 +25,17 @@ config = AppConfig()
 #   - HEALTH_CHECK_PATH: 健康检查路径（默认 /api/health）
 #   - HEALTH_CHECK_ENABLED: 是否启用（默认 true）
 #
-# 日志拦截：
-#   框架默认拦截 uvicorn/sqlalchemy.engine，可通过 intercept_loggers 追加额外的 logger
+# 日志：
+#   框架自动全局接管所有 logging，无需配置
+#   要查看 TRACE 级别日志，设置 LOG__LEVEL=TRACE
+#   要屏蔽某些库的 DEBUG 日志，使用 logger_levels 参数
 #
 app = FoundationApp(
     title="{project_name}",
     version="0.1.0",
     description="{project_name} - 基于 Aury Boot",
     config=config,
-    intercept_loggers=[],
+    # logger_levels=[("sse_starlette", "WARNING")],  # 可选：设置特定库的日志级别
 )
 
 # 注册 API 路由

{aury_boot-0.0.33 → aury_boot-0.0.35}/aury/boot/commands/worker.py

@@ -100,9 +100,12 @@ def run_worker(
         module = __import__(module_path, fromlist=[app_name])
         application = getattr(module, app_name)
 
-        # 设置日志上下文
-        from aury.boot.common.logging import set_service_context
-        set_service_context("worker")
+        # 设置日志（必须在其他操作之前）
+        from aury.boot.common.logging import setup_logging
+        setup_logging(
+            log_level=getattr(application, "_config", None) and application._config.log.level or "INFO",
+            service_type="worker",
+        )
 
         # 尝试导入 dramatiq
         try:

{aury_boot-0.0.33 → aury_boot-0.0.35}/aury/boot/common/logging/__init__.py

@@ -41,14 +41,13 @@ from aury.boot.common.logging.format import (
     log_exception,
 )
 from aury.boot.common.logging.setup import (
-    DEFAULT_INTERCEPT_LOGGERS,
+    TRACE,
     register_log_sink,
-    setup_intercept,
     setup_logging,
 )
 
 __all__ = [
-    "DEFAULT_INTERCEPT_LOGGERS",
+    "TRACE",
     "ServiceContext",
     "format_exception_java_style",
     "get_class_logger",
@@ -61,7 +60,6 @@ __all__ = [
     "register_log_sink",
     "set_service_context",
     "set_trace_id",
-    "setup_intercept",
     "setup_logging",
 ]
 

{aury_boot-0.0.33 → aury_boot-0.0.35}/aury/boot/common/logging/setup.py

@@ -11,6 +11,25 @@ from typing import Any
 
 from loguru import logger
 
+# =============================================================================
+# TRACE Level 支持
+# =============================================================================
+# 标准 logging 没有 TRACE，需要手动添加
+# TRACE (5) < DEBUG (10)，用于超细粒度调试（如每个 streaming chunk）
+TRACE = 5
+logging.addLevelName(TRACE, "TRACE")
+
+
+def _add_trace_method() -> None:
+    """为标准 logging.Logger 添加 trace() 方法。"""
+    def trace(self: logging.Logger, msg: str, *args: Any, **kwargs: Any) -> None:
+        if self.isEnabledFor(TRACE):
+            self._log(TRACE, msg, args, **kwargs)
+    
+    logging.Logger.trace = trace  # type: ignore[attr-defined]
+
+_add_trace_method()
+
 from aury.boot.common.logging.context import (
     ServiceContext,
     _to_service_context,
@@ -89,31 +108,27 @@ def register_log_sink(
     logger.debug(f"注册日志 sink: {name} (filter_key={filter_key})")
 
 
-# 默认拦截的标准 logging 日志记录器
-# - uvicorn: Uvicorn 服务器日志
-# - uvicorn.error: Uvicorn 错误日志
-# - sqlalchemy.engine: SQLAlchemy SQL 语句日志
-# 注意：uvicorn.access 不拦截，因为框架有自己的 RequestLoggingMiddleware
-DEFAULT_INTERCEPT_LOGGERS = [
-    "uvicorn",
-    "uvicorn.error",
-    "sqlalchemy.engine",
-]
-
 
 class _InterceptHandler(logging.Handler):
     """将标准 logging 日志转发到 loguru 的处理器。"""
 
     def emit(self, record: logging.LogRecord) -> None:
         # 获取对应的 loguru 级别
+        # loguru 原生支持 TRACE，标准 logging 的 TRACE(5) 会自动映射
         try:
             level = logger.level(record.levelname).name
         except ValueError:
             level = record.levelno
 
         # 查找调用者的帧深度
-        frame, depth = logging.currentframe(), 2
-        while frame and frame.f_code.co_filename == logging.__file__:
+        # 跳过 logging 模块和本文件的所有帧
+        frame = logging.currentframe()
+        depth = 0
+        while frame is not None:
+            filename = frame.f_code.co_filename
+            # 跳过 logging 模块、本文件、loguru 内部
+            if "logging" not in filename and "loguru" not in filename:
+                break
             frame = frame.f_back
             depth += 1
 
@@ -122,35 +137,22 @@ class _InterceptHandler(logging.Handler):
         )
 
 
-def _setup_intercept(logger_names: list[str]) -> None:
-    """让 loguru 接管指定的标准 logging 日志记录器。"""
-    handler = _InterceptHandler()
-    for name in logger_names:
-        std_logger = logging.getLogger(name)
-        std_logger.handlers = [handler]
-        std_logger.setLevel(logging.DEBUG)
-        std_logger.propagate = False
-
-
-def setup_intercept(logger_names: list[str] | None = None) -> None:
-    """拦截标准 logging 日志记录器并转发到 loguru。
-
-    用于独立脚本/CLI 入口点（不使用 FoundationApp 时）。
-    FoundationApp 会自动调用此函数，无需手动调用。
-
+def _setup_global_intercept(logger_levels: list[tuple[str, str]] | None = None) -> None:
+    """全局接管所有标准 logging，转发到 loguru。
+    
+    这样任何使用 logging.getLogger() 的库都会自动被接管。
+    
     Args:
-        logger_names: 额外需要拦截的 logger 名称列表，
-            会追加到默认列表 (uvicorn, sqlalchemy.engine 等)。
-
-    使用示例::
-
-        from aury.boot.common.logging import setup_logging, setup_intercept
-
-        setup_logging(log_level="DEBUG")
-        setup_intercept(["my_package", "third_party_lib"])
+        logger_levels: 需要设置特定级别的 logger 列表，格式: [("name", "LEVEL"), ...]
+            例如: [("sse_starlette", "WARNING"), ("httpx", "INFO")]
     """
-    to_intercept = DEFAULT_INTERCEPT_LOGGERS + (logger_names or [])
-    _setup_intercept(to_intercept)
+    logging.root.handlers = [_InterceptHandler()]
+    logging.root.setLevel(TRACE)  # 接收所有级别，包括 TRACE
+    
+    # 对指定的 logger 设置特定级别
+    if logger_levels:
+        for name, level in logger_levels:
+            logging.getLogger(name).setLevel(level.upper())
 
 
 def setup_logging(
@@ -162,7 +164,7 @@ def setup_logging(
     retention_days: int = 7,
     rotation_size: str = "50 MB",
     enable_console: bool = True,
-    intercept_loggers: list[str] | None = None,
+    logger_levels: list[tuple[str, str]] | None = None,
 ) -> None:
     """设置日志配置。
 
@@ -177,7 +179,7 @@ def setup_logging(
     可通过 register_log_sink() 注册额外的日志文件（如 access.log）。
 
     Args:
-        log_level: 日志级别（DEBUG/INFO/WARNING/ERROR/CRITICAL）
+        log_level: 日志级别（DEBUG/INFO/WARNING/ERROR/CRITICAL/TRACE）
         log_dir: 日志目录（默认：./logs）
         service_type: 服务类型（app/scheduler/worker）
         enable_file_rotation: 是否启用日志轮转
@@ -185,8 +187,8 @@ def setup_logging(
         retention_days: 日志保留天数（默认：7 天）
         rotation_size: 单文件大小上限（默认：50 MB）
         enable_console: 是否输出到控制台
-        intercept_loggers: 额外需要拦截的标准 logging logger 名称列表，
-            会追加到默认列表 (uvicorn, sqlalchemy.engine 等)。
+        logger_levels: 需要设置特定级别的 logger 列表，格式: [("name", "LEVEL"), ...]
+            例如: [("sse_starlette", "WARNING"), ("httpx", "INFO")]
     """
     log_level = log_level.upper()
     log_dir = log_dir or "logs"
@@ -273,16 +275,15 @@ def setup_logging(
             filter=lambda record, c=ctx: record["extra"].get("service") == c,
         )
 
-    # 拦截标准 logging 日志并转发到 loguru
-    to_intercept = DEFAULT_INTERCEPT_LOGGERS + (intercept_loggers or [])
-    _setup_intercept(to_intercept)
+    # 全局拦截标准 logging 日志并转发到 loguru
+    # 所有使用 logging.getLogger() 的库自动被接管
+    _setup_global_intercept(logger_levels=logger_levels)
 
-    logger.info(f"日志系统初始化完成 | 服务: {service_type} | 级别: {log_level} | 目录: {log_dir}")
+    logger.info
 
 
 __all__ = [
-    "DEFAULT_INTERCEPT_LOGGERS",
+    "TRACE",
     "register_log_sink",
-    "setup_intercept",
     "setup_logging",
 ]