Metadata-Version: 2.4
Name: rich-toolbox
Version: 0.1.0
Summary: A generic APIView base class for FastAPI with Tortoise ORM
Home-page: https://github.com/fzf54122/rich-utils
Author: fzf
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich
Requires-Dist: watchfiles
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: summary

# 🎨 Rich Utils

<div align="center">

**一个功能丰富的Rich库工具集合，让命令行界面变得生动多彩**

**简体中文** | [English](README.md)

[![Python](https://img.shields.io/badge/Python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![Rich](https://img.shields.io/badge/Rich-13.0+-purple.svg)](https://rich.readthedocs.io/)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

[📖 快速开始](#-快速开始) • [✨ 核心功能](#-核心功能) • [📚 API参考](#-api参考) • [🔧 高级配置](#-高级配置) • [🤝 贡献](#-贡献)

</div>

## 🌟 为什么选择 Rich Utils？

Rich Utils 是一个基于 Rich 库的工具集合，提供了丰富的命令行界面增强功能，让您的命令行应用变得更加美观和易用。

<div align="center">

| 🎨 **色彩丰富** | ⚡ **快速开发** | 📊 **可视化强** | 🛠️ **工具齐全** |
|:---:|:---:|:---:|:---:|
| 基于 Rich 库的精美界面 | 统一接口，易于使用 | 多种可视化组件 | 15+ 实用工具 |

</div>

## ✨ 核心功能

### 📝 日志记录
- **LoggerHandler** - 彩色日志输出
- **RotateLogHandler** - 日志轮转功能
- 支持不同日志级别和格式
- 文件和控制台双重输出

### 📊 可视化组件
- **ProgressHandler** - 进度条展示
- **TableHandler** - 表格数据展示
- **SpinnerHandler** - 加载动画效果
- **DashboardHandler** - 实时仪表盘
- **StatsHandler** - 统计信息展示
- **SyntaxHighlightingHandler** - 代码语法高亮
- **ColorGradientsHandler** - 颜色渐变效果

### 🛠️ 实用工具
- **ColorHandler** - 颜色处理工具
- **FileHandler** - 文件操作工具
- **FormattingHandler** - 文本格式化
- **MathHandler** - 数学计算工具
- **TimerHandler** - 计时功能
- **LayoutHandler** - 界面布局管理

## 📦 技术栈

| 组件 | 技术选型 | 版本要求 |
|------|----------|----------|
| **基础库** | Rich | 13.0+ |
| **文件监控** | watchfiles | - |
| **Python版本** | Python | 3.12+ |

## 📁 项目结构

```
rich_utils/
├── __init__.py                 # 包初始化
├── handler.py                  # 工具统一入口
├── enums.py                    # 模块枚举定义
├── config.py                   # 配置管理
├── core/                       # 核心功能模块
│   ├── __init__.py            # 核心模块初始化
│   ├── base_handler.py        # 处理器基类
│   ├── logger.py              # 日志处理器
│   ├── progress.py            # 进度条处理器
│   ├── table.py               # 表格处理器
│   ├── syntax_highlighting.py # 语法高亮处理器
│   ├── layout.py              # 布局处理器
│   ├── spinner.py             # 加载动画处理器
│   ├── color_gradients.py     # 颜色渐变处理器
│   ├── dashboard.py           # 仪表盘处理器
│   ├── stats.py               # 统计处理器
│   ├── timer.py               # 计时器处理器
│   └── rotate_log.py          # 轮转日志处理器
└── utils/                     # 实用工具模块
    ├── __init__.py            # 工具模块初始化
    ├── color.py               # 颜色工具
    ├── file.py                # 文件工具
    ├── formatting.py          # 格式化工具
    └── math.py                # 数学工具
```

## 🚀 快速开始

### ⚡ 安装

```bash
# 克隆项目
git clone https://github.com/fzf54122/rich-utils.git
cd rich-utils

# 安装依赖
pip install -e .
```

### 💻 基础使用

#### 1. 日志记录

```python
from rich_utils import RichToolbox

# 创建日志工具
logger = RichToolbox('log')

# 记录日志
logger.handle("Hello, Rich Utils!")
logger.handle("这是一条信息日志", level="info")
logger.handle("这是一条警告日志", level="warning")
logger.handle("这是一条错误日志", level="error")
```

#### 2. 进度条

```python
from rich_utils import RichToolbox
import time

# 创建进度条工具
progress = RichToolbox('progress')

# 显示进度条
for i in range(10):
    progress.handle(total=10, message=f"进度: {i+1}/10")
    time.sleep(0.5)
```

#### 3. 表格展示

```python
from rich_utils import RichToolbox

# 创建表格工具
table = RichToolbox('table')

# 显示表格
headers = ["姓名", "年龄", "职业"]
rows = [
    ["张三", "25", "工程师"],
    ["李四", "30", "设计师"],
    ["王五", "35", "产品经理"]
]
table.handle(headers=headers, rows=rows)
```

## 📚 API参考

### RichToolbox 类

统一的工具入口类，通过指定 action 参数创建不同的工具处理器。

```python
from rich_utils import RichToolbox

# 创建工具实例
tool = RichToolbox(action, config=None)
```

#### 参数
- `action`: 工具类型，可选值：`log`, `progress`, `table`, `syntax_highlighting`, `layout`, `spinner`, `color_gradients`, `dashboard`, `stats`, `timer`, `rotate_log`, `color`, `file`, `formatting`, `math`
- `config`: 配置对象（可选）

#### 方法
- `handle(**kwargs)`: 执行工具的核心功能，参数根据工具类型不同而变化

### 支持的工具类型

| 工具类型 | 描述 | 主要参数 |
|----------|------|----------|
| log | 日志记录 | message, level |
| progress | 进度条 | total, message |
| table | 表格展示 | headers, rows |
| syntax_highlighting | 语法高亮 | text |
| spinner | 加载动画 | message |
| color_gradients | 颜色渐变 | text |
| dashboard | 仪表盘 | data |
| stats | 统计信息 | data |
| timer | 计时功能 | interval |
| rotate_log | 日志轮转 | message, file_path |
| color | 颜色工具 | text, color_code |
| file | 文件工具 | file_path, data |
| formatting | 格式化工具 | text, style |
| math | 数学工具 | number |

## 🔧 高级配置

### 自定义配置

```python
from rich_utils import RichToolbox
from rich_utils.config import RichConfig

# 创建自定义配置
config = RichConfig()
config.update_config("logger", {
    "level": "debug",
    "log_format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
    "log_file": "app.log"
})

# 使用自定义配置
logger = RichToolbox('log', config)
logger.handle("这是一条调试日志", level="debug")
```

### 链式调用

```python
from rich_utils import RichToolbox

# 创建工具实例
logger = RichToolbox('log')

# 链式调用
logger.handle("第一条日志").handle("第二条日志", level="warning").handle("第三条日志", level="error")
```

## 📦 依赖

- **Rich** - 命令行富文本库
- **watchfiles** - 文件监控库

## 🤝 贡献

欢迎提交Issue和Pull Request来帮助改进这个项目！

### 贡献流程

1. Fork项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启Pull Request

## 📄 许可证

本项目采用MIT许可证 - 详情请查看 [LICENSE](LICENSE) 文件

## 💖 致谢

- 感谢 [Rich](https://github.com/Textualize/rich) 提供优秀的命令行富文本库
- 感谢所有使用和支持这个项目的开发者！

> 🚀 **开始使用**：按照快速开始指南，几分钟内即可体验 Rich Utils 的强大功能！
