yltop 0.1.2

The log module is currently implemented to replace logging. And other small wheels

yltop-recording 日志系统使用文档

简介

yltop.recording 是 yltop 包下的核心日志记录与校验模块，提供结构化日志管理、自动参数校验、异常捕获日志三大核心能力，支持多平台兼容（Windows/macOS/Linux），适用于各类 Python 应用的日志追踪与错误排查。

一、包结构概述

recording 模块采用分层设计，职责划分明确，目录结构如下：

yltop/recording/
├── __init__.py               # 公共API导出（装饰器、核心异常等）
├── core/                     # 日志核心功能
│   ├── logger.py             # 日志记录核心（格式化、写入、轮转逻辑）
│   ├── config.py             # 日志配置管理（路径、格式、级别、编码等）
│   └── handler.py            # 日志处理器（轮转策略、多线程安全控制）
├── checks/                   # 校验模块
│   ├── decorator_checker.py  # 装饰器校验（@validate_parameters 等）
│   ├── path_checker.py       # 路径校验（格式合法性、文件存在性）
│   ├── type_checker.py       # 数据类型校验（基础类型/自定义类型）
│   └── factory.py            # 校验器工厂（统一管理/调用各类校验器）
├── errors/                   # 自定义异常体系
│   ├── base.py               # 基础异常类（BaseCustomError，含错误定位能力）
│   ├── parameter.py          # 参数异常（缺失/类型不匹配/范围错误等）
│   ├── path.py               # 路径异常（格式错误/文件不存在/权限不足等）
│   └── errors.py             # 通用异常（类型错误、键不存在、执行超时等）
├── utils/                    # 工具函数
│   ├── object.py             # 对象定位（模块/函数路径）、类型识别
│   ├── path.py               # 跨平台路径处理（标准化/创建目录/权限检查）
│   └── log_parsing.py        # 日志解析（提取关键字/统计错误频率）
└── analysis/                 # 日志分析
    └── reporter.py           # 日志统计报告（错误类型分布、时段频率分析）

二、核心功能

1. 自定义异常体系

• 覆盖参数、路径、类型、执行等全场景异常类（如 ParameterTypeError、PathNotExistsError）
• 支持多语言错误消息（中文 / 英文，通过 LogConfig.language 配置）
• 自动捕获错误位置（触发异常的文件路径、行号），便于快速定位问题

2. 智能日志管理

• 自动日志轮转：支持按文件大小（max_size）或日期分割，Windows 环境下支持安全轮转（避免文件占用冲突）
• 多线程安全：基于 RLock 实现日志写入锁，防止多线程并发写入导致的日志错乱
• 灵活配置：可自定义日志目录（log_dir）、编码（encoding）、日志格式（format_str）
• 单例日志器：通过 LoggerManager 管理日志实例，确保多模块共用时唯一性

3. 参数校验工具

• 装饰器 @validate_parameters：自动校验函数参数的类型、数量、范围，不符合时抛出对应异常并记录日志
• 基础校验函数：check_path（路径有效性）、check_type（类型匹配）、check_key（字典键存在性）等，支持直接调用

4. 函数错误日志装饰器

• @log_function_errors：自动捕获函数执行中的异常，记录详细日志（含参数上下文），支持配置 continue_on_error（是否中断程序）、logger_name（指定日志器）
• @require_logger：确保日志系统初始化后再执行函数，避免未初始化导致的日志丢失

三、快速使用示例

1. 日志初始化（核心步骤）

首先通过 LogConfig 配置日志参数，再通过 LoggerManager 创建日志实例：

from yltop.recording.core import LoggerManager, LogConfig

# 1. 配置日志（Windows建议用utf-8-sig编码避免中文乱码）
log_config = LogConfig(
    name="my_app",          # 日志器名称（唯一标识）
    log_dir="logs",         # 日志存储目录（自动创建）
    max_size=10 * 1024 * 1024,  # 单个日志文件最大10MB（触发轮转）
    backups=5,              # 保留5个备份文件（超出自动删除旧文件）
    language="zh",          # 错误消息语言（zh=中文，en=英文）
    encoding="utf-8-sig"    # 日志文件编码（Windows推荐utf-8-sig）
)

# 2. 创建/获取日志器（单例模式，重复调用返回同一实例）
logger = LoggerManager.create_logger(logger_name="my_app", config=log_config)

2. 记录日志

支持 INFO/WARNING/ERROR/CRITICAL 等日志级别，可记录普通信息或异常：

# 记录普通信息（INFO级别）
logger.record("INFO", "应用启动成功，版本：v1.0.0")

# 记录异常（ERROR级别，含异常上下文）
try:
    # 模拟业务错误
    result = 10 / 0
except ZeroDivisionError as e:
    logger.record("ERROR", f"计算模块执行失败：{str(e)}", exc_info=True)
    # exc_info=True：自动记录异常堆栈信息（便于排查）

3. 参数校验装饰器

用 @validate_parameters 自动校验函数参数类型 / 数量：

from yltop.recording import validate_parameters

# 启用类型校验：自动检查参数类型是否匹配注解
@validate_parameters(enable_type_check=True)
def add_numbers(a: int, b: int) -> int:
    """两数相加，要求参数均为int类型"""
    return a + b

# 正常调用（无异常）
add_numbers(10, 20)  # 返回30

# 异常调用（参数类型不匹配）
add_numbers(10, "20")  # 自动抛出ParameterTypeError，日志记录错误信息

4. 函数错误日志装饰器

用 @log_function_errors 自动捕获函数异常并记录，不中断程序：

from yltop.recording import log_function_errors

# 配置：指定日志器、捕获异常后继续执行
@log_function_errors(logger_name="my_app", continue_on_error=True)
def risky_operation(file_path: str):
    """模拟高风险操作（如文件读写）"""
    with open(file_path, "r", encoding="utf-8") as f:
        return f.read()

# 调用不存在的文件（触发异常）
risky_operation("nonexistent_file.txt")  
# 结果：异常被捕获并记录日志，程序继续执行（不崩溃）

四、注意事项

1. Windows 编码问题：默认编码为 utf-8，若出现中文乱码，需在 LogConfig 中指定 encoding="utf-8-sig"。
2. 日志文件大小控制：生产环境务必配置 max_size 和 backups，避免单个日志文件过大（影响读取）或占用过多磁盘空间。
3. 多模块日志共用：不同模块需使用同一日志器时，通过 LoggerManager.get_logger("my_app") 获取实例（而非重复创建）。
4. 资源释放：应用退出前，建议调用 LoggerManager.clear_all_loggers() 释放日志文件句柄，避免资源泄漏。
5. 异常堆栈记录：记录异常时建议添加 exc_info=True（如 logger.record("ERROR", msg, exc_info=True)），便于后续排查完整异常链路。

五、更多信息

• 模块详细文档可查看包内文件：yltop/recording/readme.txt
• 若需反馈问题或提需求，可通过项目仓库的 Issues 功能提交。