taskbar 1.0.1

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

皛鲸任务进度条 (TaskBar)

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

✨ 特性

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

🚀 快速安装

pip install xiaojing-taskbar

📖 基本使用

1. 最简单的使用方式

import time
from taskbar import TaskBar

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

2. 使用便利函数

import time
from taskbar import TaskBar

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

3. 处理复杂数据结构

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="")

🎯 高级用法

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

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所有线程完成！")

进程安全模式

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所有进程完成！")

自定义打印函数

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)

禁用彩色输出

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 便利函数

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！

📧 联系

作者：皛鲸 ([e-mail])

---

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