cprintf 0.1.12

Printing and debugging with color

cprintf

一个增强版的彩色终端打印与日志格式化输出工具库。

安装

pip install cprintf

主要功能

• 日志级别控制：提供 DEBUG、INFO、WARNING 、ERROR（或简写 ERR）、FATAL 五种日志级别控制。通过 set_log_level() 动态调整过滤级别。
• 原生多参数支持：支持像原生 print 一样传入多个参数（*args），并支持使用 sep 控制分隔符，支持 prefix 和 suffix 参数。
• 中文字符表格对齐：智能识别中文字符（CJK）终端实际显示宽度，支持左对齐、右对齐与居中对齐，支持不规则列数据安全补齐。
• 线程安全：内部采用线程互斥锁，多线程并发时输出不乱序、不插断。
• 进度条：优雅且健壮的进度渲染，支持除零与溢出防护，以及自定义颜色。
• 自动格式化：智能检测 dict/list 复杂数据结构并自动进行 JSON 缩进美化或 pprint 呈现，并进行了 JSON 首字符快速前置过滤以提高性能。
• 时间戳输出：一键开启时间戳日志前缀（timestamp=True）。

使用示例

1. 基础彩色日志与多参数支持

import cprintf

# 设置日志级别（默认是 INFO）
cprintf.set_log_level('DEBUG')

# 基础打印
cprintf.debug("这是一条调试信息")
cprintf.info("普通字符串")
cprintf.ok("这是一条成功或确认信息")
cprintf.warn("这是一条警告信息")
cprintf.err("这是一条错误信息")

# 支持多参数打印（类似于内置 print）
cprintf.info("参数1", "参数2", "参数3", sep=" | ", prefix="[APP] ", suffix=" [END]")
cprintf.ok("解析结果：", {"status": "success", "code": 200}, sep=" ==> ")

2. 带时间戳的日志

cprintf.info("这是一条带时间戳的信息", timestamp=True)
# 输出: [2026-06-24 17:30:10] 这是一条带时间戳的信息

3. 表格打印（支持中文字符与对齐方式）

print_table 完美支持中英文字符混排、显示宽度对齐，并支持 left（左对齐，默认）、right（右对齐）、center（居中对齐）。

headers = ["项目名称", "当前进度", "运行状态"]
data = [
    ["项目A（核心系统）", "75.5%", "进行中"],
    ["项目B（辅助工具）", "100.0%", "已完成"],
    ["项目C", "0.0%", "未开始"]
]

# 居中对齐表格
cprintf.print_table(data, headers=headers, color='OK', align='center')

4. 进度条

import time

for i in range(100):
    time.sleep(0.05)
    color = 'OK' if i < 50 else 'WARNING' if i < 80 else 'ERR'
    cprintf.progress_bar(i + 1, 100, prefix='处理中:', suffix=f'阶段 {i//20 + 1}', color=color)

5. 分割线与自定义颜色

# 打印一条分割线
cprintf.line(char='=', length=60, color='OK')

# 自定义 ANSI 颜色码输出
cprintf.custom("This is a custom color message in cyan!", "\033[96m")

# 仅获取带 ANSI 颜色代码的字符串而不进行打印
colored_str = cprintf.get_colored_string("这是一个带颜色的字符串", color='WARNING')
print(colored_str)

格式化模式

可以使用 format_mode 显式控制复杂对象格式化：

• 'auto' (默认)：如果是 dict/list 且符合 JSON 规范，则转为美化 JSON；若不是则使用 pprint。
• 'json'：强制转换为美化 JSON。
• 'pprint'：强制使用 pprint.pformat 格式化。
• 'raw'：强转为原始字符串，如 str() 或 repr()。