ColorInfo 🌈

一个功能强大的 Python 彩色日志工具，支持结构化日志记录，参考 loguru 设计实现全局配置同步

📊 项目状态

🎯 核心特性

✨ 主要特性

• 🎨 彩色输出 - 终端彩色日志显示
• 📝 结构化日志 - 类似 Go Zap 的字段式日志记录
• 🌐 多格式支持 - 纯文本和 JSON 格式输出
• � 全局配置 - 参考 loguru 设计，一处配置全局同步
• 📊 多输出等级 - 支持不同输出目标设置不同日志级别
• ⏰ 时间格式 - 支持自定义时间格式和多种预设格式
• �🔧 使用简单 - 简洁的 API 设计
• 🎯 中文注释 - 完整的中文文档和注释
• 🐍 版本兼容 - 支持全部 Python3 版本 (>=3.0)
• 📊 参数灵活 - 支持传入多个参数，无需格式化
• 🔍 智能定位 - 自动显示调用文件和行号信息

📦 安装教程

快速安装

pip3 install --upgrade ColorInfo-liumou-Stable

开发安装

git clone https://gitee.com/liumou_site/ColorInfo.git
cd ColorInfo
pip3 install -e .

验证安装

# 测试安装是否成功
from ColorInfo_liumou_Stable import logger
logger.info("✅ ColorInfo 安装成功！")

🚀 快速开始

新版全局 Logger（推荐）

参考 loguru 设计，只需在一个地方配置，所有模块自动同步：

from ColorInfo_liumou_Stable import logger
import sys

# 添加文件处理器（文件输出INFO级别，控制台输出DEBUG级别）
logger.add("app.log", level="INFO")
logger.add(sys.stdout, level="DEBUG")

# DEBUG级别只在控制台显示
logger.debug("调试信息")

# INFO级别在控制台和文件都显示
logger.info("应用启动")

# 结构化日志
logger.bind(user_id=123).info("用户登录", ip="192.168.1.1")

多输出等级配置

from ColorInfo_liumou_Stable import logger
import sys

# 清除默认处理器
logger.remove()

# 控制台输出 DEBUG 及以上级别
logger.add(sys.stdout, level="DEBUG", colorize=True)

# 文件只输出 INFO 及以上级别
logger.add("app.log", level="INFO")

# 错误日志单独输出到 error.log
logger.add("error.log", level="ERROR")

logger.debug("这条只在控制台显示")
logger.info("这条在控制台和文件都显示")
logger.error("这条在所有地方都显示")

时间格式设置

from ColorInfo_liumou_Stable import logger

# 使用预设格式
logger.set_time_format(preset='iso')       # ISO格式: 2026-02-03T20:18:51
logger.set_time_format(preset='compact')   # 紧凑格式: 20260203_201851
logger.set_time_format(preset='verbose')   # 中文格式: 2026年02月03日 20时18分51秒

# 使用自定义格式
logger.set_time_format(fmt='%Y/%m/%d %H:%M:%S.%f')  # 带毫秒

# 使用12小时制
logger.set_time_format(preset='us', use_24h=False)  # 02/03/2026 08:18:51 PM

结构化日志

from ColorInfo_liumou_Stable import logger

# 方式1: 使用 bind 创建带默认字段的 logger
user_logger = logger.bind(user_id=12345, username='admin')
user_logger.info("用户登录", ip='192.168.1.1')
user_logger.error("登录失败", reason="密码错误")

# 方式2: 链式调用
logger.bind(request_id="abc-123").info("处理请求", method="GET", path="/api/users")

# 方式3: as_structured 模式
logger.as_structured(app="MyApp", version="1.0.0")
logger.info("服务启动", port=8080)

# 切换回普通模式
logger.as_plain()

高级配置

from ColorInfo_liumou_Stable import logger
import sys

# 批量配置
logger.configure(
    handlers=[
        {"sink": sys.stdout, "level": "DEBUG", "colorize": True},
        {"sink": "app.log", "level": "INFO"},
        {"sink": "error.log", "level": "ERROR", "serialize": True},  # JSON格式
    ],
    extra={"service": "my-service", "version": "2.0.0"}
)

# 设置格式选项
logger.set_format(
    date_on=True,      # 显示日期
    time_on=True,      # 显示时间
    filename_on=True,  # 显示文件名
    class_on=True,     # 显示类名
    fun_on=True,       # 显示函数名
    line=True,         # 显示行号
    level=True         # 显示日志级别
)

📋 完整示例

全局 Logger 示例

from ColorInfo_liumou_Stable import logger
import sys

def main():
    # 配置日志
    logger.add("app.log", level="INFO")
    logger.set_time_format(preset='iso')
    
    # 记录日志
    logger.debug("调试信息")
    logger.info("应用启动")
    logger.warning("警告信息")
    logger.error("错误信息")
    
    # 结构化日志
    logger.bind(user_id=123).info("用户操作", action="login")

if __name__ == "__main__":
    main()

多模块配置同步示例

# config.py - 配置模块
from ColorInfo_liumou_Stable import logger
import sys

# 在一个地方配置
logger.add("app.log", level="INFO")
logger.add(sys.stdout, level="DEBUG")

# main.py - 主模块
from ColorInfo_liumou_Stable import logger
from config import logger as config_logger  # 自动使用 config.py 的配置

logger.info("主模块日志")  # 使用 config.py 的配置

# module_a.py - 其他模块
from ColorInfo_liumou_Stable import logger

logger.debug("模块A调试")  # 同样使用 config.py 的配置

传统 ColorLogger（向后兼容）

from ColorInfo_liumou_Stable import ColorLogger

# 创建日志记录器
log = ColorLogger(txt=True, fileinfo=True, basename=False)

# 记录不同级别的日志
log.info('信息消息')
log.error('错误消息')
log.debug('调试消息')
log.warning('警告消息')

🎨 输出效果

控制台输出

日志会在控制台显示彩色输出，包含时间、文件名、行号、类名、函数名和日志内容。

2026-02-03T20:18:51 demo.py line: 25 Function: main INFO : 应用启动
2026-02-03T20:18:51 demo.py line: 26 Function: main ERROR : 错误信息

文件输出

同时支持将日志写入文件，包含完整的结构化信息：

2026-02-03 20:18:51 demo.py line: 17 Function: demos INFO : 1 x=23
2026-02-03 20:18:51 demo.py line: 18 Function: demos ERROR : 2 22 222
2026-02-03 20:18:51 structured.py line: 93 Class: StructuredLogger Function: info INFO : 用户登录 user_id=12345 username=admin ip=192.168.1.1

JSON 格式输出

{"timestamp": "2026-02-03T20:18:51.570094", "level": "INFO", "message": "JSON格式日志 app=DemoApp version=2.0.0 user_id=123 action=login service=demo-service", "file": "demo.py", "line": 167, "function": "demo_json_output", "fields": {"app": "DemoApp", "version": "2.0.0", "user_id": 123, "action": "login", "service": "demo-service"}}

🛠️ API 参考

全局 Logger（推荐）

• logger.add(sink, level="DEBUG", **kwargs) - 添加日志处理器
• logger.remove(handler_id=None) - 移除处理器
• logger.configure(**kwargs) - 批量配置
• logger.set_format(**kwargs) - 设置格式选项
• logger.set_time_format(**kwargs) - 设置时间格式
• logger.bind(**fields) - 创建带默认字段的 logger
• logger.as_structured(**fields) - 切换为结构化模式
• logger.as_plain() - 切换为普通模式
• logger.debug/info/warning/error(msg, **fields) - 记录日志

时间格式预设

预设名称	格式	示例
default	%Y-%m-%d %H:%M:%S	2026-02-03 20:18:51
iso	%Y-%m-%dT%H:%M:%S	2026-02-03T20:18:51
compact	%Y%m%d_%H%M%S	20260203_201851
time_only	%H:%M:%S	20:18:51
date_only	%Y-%m-%d	2026-02-03
us	%m/%d/%Y %I:%M:%S %p	02/03/2026 08:18:51 PM
eu	%d/%m/%Y %H:%M:%S	03/02/2026 20:18:51
verbose	%Y年%m月%d日 %H时%M分%S秒	2026年02月03日 20时18分51秒

ColorLogger 类（向后兼容）

• info(msg, *args) - 记录信息级别日志
• error(msg, *args) - 记录错误级别日志
• debug(msg, *args) - 记录调试级别日志
• warning(msg, *args) - 记录警告级别日志
• set_level(console, text) - 设置日志级别
• set_format(**kwargs) - 设置格式选项

结构化日志类（向后兼容）

• StructuredLogger(base_logger) - 字段式结构化日志
• JSONStructuredLogger(base_logger) - JSON 格式结构化日志
• sugar(logger) - 将普通日志转换为结构化日志

🔗 项目链接

• PyPI 主页: https://pypi.org/project/ColorInfo-liumou-Stable/
• Gitee 仓库: https://gitee.com/liumou_site/ColorInfo.git

📸 效果截图

请在 Gitee 项目主页查看详细的彩色日志效果图片

📄 许可证

本项目采用开源许可证，详见项目仓库

---

ColorInfo - 让 Python 日志记录变得简单而强大！🚀