Quick-Logger-Colorful：轻量无依赖的 Python 彩色日志库，同步异步双支持

Quick-Logger-Colorful：轻量无依赖的Python彩色日志库，同步异步双支持

• 介绍
• 项目核心信息
• 核心特性
• 安装方式
  • 推荐：PyPI安装（一键完成）
  • 本地源码安装
• 快速上手
  • 1. 同步日志（核心模块，适用于普通脚本/Flask/Django）
  • 2. 异步日志（asynclog模块，适用于FastAPI/Sanic）
  • 3. 模式切换（调试/生产模式）
• 配置说明
  • 自动生成配置文件
  • 配置参数说明
  • 自定义配置示例
• 兼容性说明
• 常见问题（FAQ）
• 贡献指南
• 开源协议

介绍

在Python开发中，日志是排查问题、追踪流程的核心工具，但原生logging配置繁琐，第三方日志库常依赖过重或功能冗余。为此，我开发了Quick-Logger-Colorful——一款轻量化、零配置、支持彩色输出与同步/异步双模式的Python日志工具，无需复杂配置，开箱即用，完美适配各类Python项目。

项目核心信息

• 项目名称：Quick-Logger-Colorful
• 当前版本：v0.4.0
• Python支持：3.7 | 3.8 | 3.9 | 3.10 | 3.11 | 3.12
• 开源协议：MIT
• 核心定位：轻量、无依赖、高兼容性，专注日志核心需求的工具库

核心特性

✅ 分级日志：支持5级日志分级，满足不同场景需求

• DEBUG(0)：调试日志，开发阶段使用
• INFO(1)：信息日志，记录正常业务流程
• WARN(2)：警告日志，提示潜在风险
• ERROR(3)：错误日志，记录异常情况
• FATAL(4)：致命日志，标记严重错误

🎨 彩色终端输出：不同级别日志采用差异化颜色，视觉区分更清晰

• DEBUG：青色
• INFO：绿色
• WARN：黄色
• ERROR：红色
• FATAL：红底白字（醒目突出，快速锁定关键错误）

🐛 自动异常捕获：单行动态装饰器，同时支持同步/异步函数，用户可以定义某些异常自动标记为FATAL级别，完整记录堆栈信息

⚙️ 零配置开箱即用：首次运行自动创建日志目录和配置文件，无需手动初始化，新手秒上手

📅 按日拆分日志：自动生成每日独立日志文件，避免单文件过大，便于日志归档与查询

🔄 同步异步双模式：核心模块支持同步日志，asynclog模块支持异步日志，适配不同项目架构

🌍 模式快速切换：通过-O命令行参数，一键切换调试/生产模式，灵活控制日志输出级别

安装方式

推荐：PyPI安装（一键完成）

pip install quick-logger-colorful 

本地源码安装

# 克隆仓库git clone https://github.com/huyuenshen/quick-logger.git cd quick-logger # 源码安装 pip install.

快速上手

1. 同步日志（核心模块，适用于普通脚本/Flask/Django）

from quick_logger import Logger, start_logger # 初始化日志器（自动创建日志目录和配置文件） logger = Logger()# 输出不同级别日志（通过typ参数指定级别） logger.log("This is a DEBUG message", typ=0) logger.log("This is an INFO message", typ=1) logger.log("This is a WARN message", typ=2) logger.log("This is an ERROR message", typ=3) logger.log("This is a FATAL message", typ=4)# 红底白字输出# 装饰器捕获异常（某些异常自动标记为FATAL级别）@start_logger()deftest_function(): logger.log("Running sync test function", typ=1)raise KeyError("Critical error (marked as FATAL)")# 触发ERROR级日志if __name__ =="__main__":try: test_function()except Exception:pass

2. 异步日志（asynclog模块，适用于FastAPI/Sanic）

import asyncio from quick_logger import asynclog asyncdefasync_test_func():# 初始化异步日志器 logger = asynclog.Logger()await logger.log("This is an async INFO message", typ=1)await logger.log("This is an async FATAL message", typ=4)# 异步FATAL日志await asyncio.sleep(1)# 模拟异步任务（无阻塞）# 异步函数异常捕获装饰器@asynclog.start_logger(fatals=[ImportError])# 自定义FATALasyncdefwrapped_async_func():await async_test_func()raise ImportError("Async fatal error")# 触发异步FATAL日志if __name__ =="__main__": asyncio.run(wrapped_async_func())

3. 模式切换（调试/生产模式）

生产模式：隐藏DEBUG级别，仅输出INFO/WARN/ERROR/FATAL

python your_script.py -O 

调试模式（默认）：输出所有级别日志（DEBUG/INFO/WARN/ERROR/FATAL）

python your_script.py 

配置说明

自动生成配置文件

首次运行后，会在项目目录下创建配置文件：./Logger/.config/Config.json，默认配置如下：

{"pattern":"[{time}][{func}][{level}]:{msg}","file":"./Logger/{date}.log.txt","enable_color":true}

配置参数说明

• pattern：日志格式模板，支持4个占位符
  • {time}：日志输出时间（默认格式：HH:MM:SS）
  • {func}：日志所在函数名
  • {level}：日志级别（DEBUG/INFO/WARN/ERROR/FATAL）
  • {msg}：日志内容
• file：日志文件路径，{date}自动替换为当前日期（默认格式：YYYY-MM-DD）
• enable_color：是否启用终端彩色输出（默认：true）

自定义配置示例

1. 修改日志格式：

{"pattern":"[{time}] [{level}] [{func}] - {msg}","file":"./Logger/{date}.log.txt","enable_color":true}

2. 禁用彩色输出（适用于非交互式终端）：

{"pattern":"[{time}][{func}][{level}]:{msg}","file":"./Logger/{date}.log.txt","enable_color":false}

3. 自定义日志日期格式：

{"pattern":"[{time}][{func}][{level}]:{msg}","file":"./Logger/{date:%Y%m%d}.log.txt"}

4. 修改默认日志目录（支持绝对路径）：

// Linux/macOS{"pattern":"[{time}][{func}][{level}]:{msg}","file":"/var/log/my_project/{date}.log.txt"}// Windows{"pattern":"[{time}][{func}][{level}]:{msg}","file":"D:\\Logs\\my_project\\{date}.log.txt"}

兼容性说明

• Python版本：支持3.7及以上所有3.x版本
• 运行平台：Windows、macOS、Linux、Android（支持Pydroid等Python编译器）
• 框架适配：
  • FastAPI（异步）：使用asynclog.Logger，日志调用前加await，装饰器用@asynclog.start_logger()
  • Django/Flask（同步）：直接使用核心Logger类，装饰器用@start_logger()，建议全局初始化一次（如在settings.py中）

常见问题（FAQ）

1. FATAL日志未输出到文件/终端？
   • 确认typ=4参数传递正确（FATAL级别唯一对应值为4）；
   • 检查是否误启用-O生产模式（生产模式仅隐藏DEBUG，不影响FATAL）；
   • 验证./Logger/目录的读写权限（库不会主动抛出权限异常）。
2. 如何禁用终端彩色输出？
   • 手动创建/修改./Logger/.config/Config.json，添加"enable_color": false字段，重启脚本即可生效。
3. 异步日志阻塞事件循环？
   • 异步函数中必须使用quick_logger.asynclog.Logger，不可使用同步版Logger；
   • 异步日志调用必须加await关键字（如await logger.log(...)），缺失会导致同步阻塞。
4. 如何避免框架中日志重复输出？
   • 不要重复初始化Logger，建议在项目全局（如settings.py/__init__.py）初始化一次，其他文件导入使用。
5. 如何自定义FATAL异常？

在装饰器的参数中加上fatals=[...]并在列表里面写上你要自定义的异常，如：

@quick_logger.start_logger(fatals=[ImportError, IndexError])deffunc(): a =[0,1,2]return a[3]# 抛出IndexError，命中FATAL条件

贡献指南

欢迎通过Issue提交bug反馈或功能建议，也可直接提交Pull Request参与开发。对于重大功能变更，建议先通过Issue讨论方案，再进行开发。

开源协议

本项目基于MIT开源协议，可自由使用、修改、商用，详见项目根目录下的LICENSE文件。

• GitHub仓库：https://github.com/huyuenshen/quick-logger（欢迎Star⭐️支持）
• PyPI地址：https://pypi.org/project/quick-logger-colorful/
• 若使用过程中遇到问题，可通过GitHub Issue或评论区反馈，将及时响应处理！