# ColorInfo

**Repository Path**: liumou_site/ColorInfo

## Basic Information

- **Project Name**: ColorInfo
- **Description**: 一个使用Python3编写的简单的彩色日志工具
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: https://liumou.site/doc/560
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2022-10-26
- **Last Updated**: 2026-02-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ColorInfo 🌈

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

## 📊 项目状态

[![PyPI 版本](https://img.shields.io/pypi/v/ColorInfo-liumou-Stable.svg?color=blue)](https://pypi.org/project/ColorInfo-liumou-Stable/)
[![PyPI 下载量](https://img.shields.io/pypi/dm/ColorInfo-liumou-Stable.svg?color=green)](https://pypi.org/project/ColorInfo-liumou-Stable/)
[![Python 版本](https://img.shields.io/pypi/pyversions/ColorInfo-liumou-Stable.svg?color=orange)](https://pypi.org/project/ColorInfo-liumou-Stable/)
[![许可证](https://img.shields.io/pypi/l/ColorInfo-liumou-Stable.svg?color=red)](https://gitee.com/liumou_site/ColorInfo/blob/master/LICENSE)
[![代码大小](https://img.shields.io/github/languages/code-size/liumou_site/ColorInfo.svg?color=purple)](https://gitee.com/liumou_site/ColorInfo)
[![最后提交](https://img.shields.io/github/last-commit/liumou_site/ColorInfo.svg?color=yellow)](https://gitee.com/liumou_site/ColorInfo/commits/master)

## 🎯 核心特性

![结构化日志](https://img.shields.io/badge/结构化日志-支持-brightgreen.svg)
![彩色输出](https://img.shields.io/badge/彩色输出-支持-ff69b4.svg)
![JSON格式](https://img.shields.io/badge/JSON格式-支持-blue.svg)
![Go Zap风格](https://img.shields.io/badge/Go%20Zap风格-支持-orange.svg)
![全局配置](https://img.shields.io/badge/全局配置-同步-cyan.svg)
![多输出等级](https://img.shields.io/badge/多输出等级-支持-yellow.svg)
![时间格式](https://img.shields.io/badge/时间格式-可配置-purple.svg)
![中文文档](https://img.shields.io/badge/中文文档-完整-red.svg)

## ✨ 主要特性

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

## 📦 安装教程

### 快速安装

```shell
pip3 install --upgrade ColorInfo-liumou-Stable
```

### 开发安装

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

### 验证安装

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

## 🚀 快速开始

### 新版全局 Logger（推荐）

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

```python
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")
```

### 多输出等级配置

```python
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("这条在所有地方都显示")
```

### 时间格式设置

```python
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
```

### 结构化日志

```python
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()
```

### 高级配置

```python
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 示例

```python
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()
```

### 多模块配置同步示例

```python
# 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（向后兼容）

```python
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 格式输出

```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/](https://pypi.org/project/ColorInfo-liumou-Stable/)
* **Gitee 仓库**: [https://gitee.com/liumou_site/ColorInfo.git](https://gitee.com/liumou_site/ColorInfo.git)

## 📸 效果截图

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

![logg.png](./Demo.png)

## 📄 许可证

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

---

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