Metadata-Version: 2.4
Name: cprintf
Version: 0.1.12
Summary: Printing and debugging with color
Home-page: https://github.com/wang-zhibo/cprintf
Author: gm.zhibo.wang
Author-email: gm.zhibo.wang@gmail.com
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-python
Dynamic: summary

# cprintf

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

## 安装

```bash
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. 基础彩色日志与多参数支持

```python
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. 带时间戳的日志

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

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

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

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

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

### 4. 进度条

```python
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. 分割线与自定义颜色

```python
# 打印一条分割线
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()`。
