Metadata-Version: 2.1
Name: taskbar
Version: 1.0.2
Summary: 一个功能丰富、彩色显示、支持多线程/多进程的任务进度条库。让您的循环处理过程一目了然！
Home-page: https://github.com/lqxnjk/taskbar
Author: lqxnjk
Author-email: lqxnjk@qq.com
License: MIT
Project-URL: Bug Reports, https://github.com/lqxnjk/taskbar/issues
Project-URL: Source, https://github.com/lqxnjk/taskbar
Keywords: task,bar,rule,tool,data
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.7
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: typing-extensions; python_version < "3.8"
Provides-Extra: dev
Provides-Extra: plot
Provides-Extra: gpu
Provides-Extra: full
Requires-Dist: taskbar[dev]; extra == "full"
Requires-Dist: taskbar[plot]; extra == "full"
Requires-Dist: taskbar[gpu]; extra == "full"

# 皛鲸任务进度条 (TaskBar)

一个功能丰富、彩色显示、支持多线程/多进程的任务进度条库。让您的循环处理过程一目了然！

## ✨ 特性

- 🎨 **彩色输出** - 支持ANSI彩色显示，进度信息层次分明
- 📊 **丰富的进度信息** - 显示百分比、完成数量、当前处理值
- ⏱️ **完整的时间统计** - 平均耗时、最后一次耗时、已用时间、预计结束时间
- 🔒 **线程安全** - 支持多线程环境下的安全更新
- 🔄 **进程安全** - 支持多进程环境下的安全更新（通过共享内存）
- 🎯 **灵活的使用方式** - 支持迭代器模式和手动更新模式
- 📝 **可自定义打印** - 支持自定义打印函数，方便集成到不同环境

## 🚀 快速安装

```bash
pip install taskbar
```

## 📖 基本使用

### 1. 最简单的使用方式

```python
import time
from taskbar import TaskBar

# 直接包装可迭代对象
for i in TaskBar(range(100), "处理数据"):
    time.sleep(0.01)  # 模拟耗时操作
```

### 2. 使用便利函数

```python
import time
from taskbar import TaskBar

# 使用taskbar便利函数
for i in TaskBar(range(50), n_desc="批量处理", n_interval=0.5):
    time.sleep(0.02)
```

### 3. 处理复杂数据结构

```python
import time
from taskbar import TaskBar

# 处理列表中的元组数据，会自动提取第一个元素显示
data = [(i, f"item_{i}", f"value_{i}") for i in range(20)]

for item in TaskBar(data, "处理元组数据", n_interval=0.3):
    time.sleep(0.05)
    # item 是原始数据，可以正常使用
    print(f"\n  处理: {item}", end="")
```

## 🎯 高级用法

### 手动更新模式（适用于多线程）

```python
import time
import threading
from taskbar import TaskBar

def worker(taskbar, worker_id):
    """工作线程函数"""
    for i in range(5):
        time.sleep(0.1)
        taskbar.update()  # 手动更新进度
        taskbar.val = f"worker-{worker_id}-{i}"  # 设置当前处理的值

# 创建TaskBar实例，不传入迭代器
tb = TaskBar(n_desc="多线程处理", n_total=20)

# 启动多个线程
threads = []
for i in range(4):
    t = threading.Thread(target=worker, args=(tb, i))
    t.start()
    threads.append(t)

# 等待所有线程完成
for t in threads:
    t.join()

print("\n所有线程完成！")
```

### 进程安全模式

```python
import time
import multiprocessing
from taskbar import TaskBar

def worker_process(taskbar, process_id):
    """工作进程函数"""
    for i in range(3):
        time.sleep(0.2)
        taskbar.update()  # 进程安全地更新
        taskbar.val = f"process-{process_id}-{i}"

if __name__ == "__main__":
    # 启用进程安全模式
    tb = TaskBar(
        n_desc="多进程处理",
        n_total=12,
        n_interval=0.5,
        n_process=True  # 启用进程安全
    )
    
    processes = []
    for i in range(4):
        p = multiprocessing.Process(target=worker_process, args=(tb, i))
        p.start()
        processes.append(p)
    
    for p in processes:
        p.join()
    
    print("\n所有进程完成！")
```

### 自定义打印函数

```python
import time
from taskbar import TaskBar

def custom_print(message):
    """自定义打印函数，可以重定向到日志文件等"""
    with open("progress.log", "a", encoding="utf-8") as f:
        f.write(message + "\n")
    # 同时也在控制台显示
    print(message, end="", flush=True)

# 使用自定义打印函数
for i in TaskBar(
    range(30),
    n_desc="带日志记录",
    n_interval=0.2,
    n_print=custom_print
):
    time.sleep(0.03)
```

### 禁用彩色输出

```python
import time
from taskbar import TaskBar

# 在不支持ANSI颜色的环境中禁用彩色输出
for i in TaskBar(range(20), "无彩色模式", n_interval=0.2, n_color=False):
    time.sleep(0.05)
```

## 📊 输出示例

当使用彩色模式时，进度条会显示：

```
处理数据|████████░░░░░░░░░░░░|50/100(50.00%) <current_value> avg:[0.12] last:[0.10] use:[0:00:06] end:[2023-01-01 10:00:00 -> 2023-01-01 10:00:06 -> 2023-01-01 10:00:12]
```

信息说明：
- **处理数据** - 任务描述（青色）
- **|████...|** - 进度条（绿色）
- **50/100(50.00%)** - 完成数量和百分比（蓝色）
- **<current_value>** - 当前处理的值（如果提供）
- **avg:[0.12]** - 平均每次耗时
- **last:[0.10]** - 最后一次耗时
- **use:[0:00:06]** - 已用时间
- **end:[...]** - 开始时间、当前时间、预计结束时间

## 🔧 API 参考

### TaskBar 类

#### 构造函数参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `n_iter` | Iterable | None | 可迭代对象，如果为None则使用手动更新模式 |
| `n_desc` | str | "" | 任务描述 |
| `n_interval` | float | 1.0 | 打印间隔（秒） |
| `n_width` | int | 20 | 进度条宽度（字符数） |
| `n_print` | Callable | None | 自定义打印函数 |
| `n_color` | bool | True | 是否使用彩色输出 |
| `n_total` | int | None | 总任务数，覆盖从iteration获取的长度 |
| `n_thread` | bool | True | 是否线程安全 |
| `n_process` | bool | False | 是否进程安全 |

#### 方法

- **`update(n=1)`** - 手动更新进度
- **`__iter__()`** - 使对象可迭代
- **`__next__()`** - 获取下一个元素

### taskbar 便利函数

```python
from taskbar import taskbar
taskbar(
    iteration=None,
    desc="",
    interval=1.0,
    width=32,
    use_color=True,
    total=None,
    thread_safe=True,
    process_safe=False
)
```

返回一个配置好的 `TaskBar` 实例。

## ⚠️ 注意事项

1. **线程/进程安全**：在多线程/多进程环境中，建议启用对应的安全模式
2. **总任务数**：如果提供了可迭代对象且有`__len__`方法，会自动获取总任务数
3. **当前值显示**：如果迭代元素是元组/列表，会自动显示第一个元素；如果元素太长（>50字符）则不显示
4. **性能影响**：进度条打印会有轻微的性能开销，建议根据任务耗时调整`interval`参数

## 📝 许可证

本项目采用 MIT 许可证。

## 🤝 贡献

欢迎提交Issue和Pull Request！

## 📧 联系

作者：皛鲸 (lqxnjk@qq.com)

---

**如果这个库对你有帮助，请给个Star⭐吧！**
