Python 如何创建和使用进度条（tqdm模块）

在处理大规模数据、运行长时间任务或者需要跟踪任务进度的场景中，进度条（Progress Bar）是非常有用的工具。Python 的 tqdm 模块提供了一种简便的方法来创建和使用进度条，它的名称来源于阿拉伯语词汇“taqaddum”，意思是“进步”。

tqdm 模块非常流行，它既可以用在命令行界面，也可以嵌入在 Jupyter Notebook 等环境中。它支持循环、文件处理、函数装饰器等多种场景。接下来，我们将详细讲解如何安装 tqdm，如何在不同的场景下创建和使用进度条，并探讨一些高级用法。

2. tqdm 模块的安装

在开始使用 tqdm 之前，需要先确保该模块已经安装。可以使用以下命令进行安装：

pip install tqdm

安装完成后，就可以在 Python 脚本或交互式环境中使用 tqdm 了。

3. 基础用法

3.1 简单的循环进度条

最常见的场景是为一个循环（例如 for 循环）添加进度条。我们只需将 tqdm 包裹在迭代对象上即可：

from tqdm import tqdm
import time

for i in tqdm(range(100)):
    time.sleep(0.1)  # 模拟一些耗时操作

运行这个代码时，你会在命令行或终端中看到一个动态更新的进度条：

  0%|          | 0/100 [00:00<?, ?it/s]
 50%|█████     | 50/100 [00:05<00:05,  9.96it/s]
100%|██████████| 100/100 [00:10<00:00,  9.97it/s]

其中：

• 0% 和 100% 表示当前进度百分比。
• | | 是一个视觉上的进度条。
• 50/100 表示已完成 50 个迭代，总共 100 个迭代。
• [00:05<00:05, 9.96it/s] 表示已经运行了 5 秒，预计剩余 5 秒，速度为 9.96 次/秒。

3.2 自定义进度条描述

可以通过 desc 参数为进度条添加描述信息，帮助用户更好地理解当前进度条的任务：

for i in tqdm(range(100), desc="Processing"):
    time.sleep(0.1)

这会在进度条前加上 Processing 文字，使输出更有意义。

4. 进阶用法

4.1 嵌套进度条

在处理嵌套循环时，可以使用多个进度条，tqdm 支持这种场景：

for i in tqdm(range(10), desc="Outer Loop"):
    for j in tqdm(range(100), desc="Inner Loop", leave=False):
        time.sleep(0.01)

这里，我们在外层循环和内层循环中都使用了 tqdm。leave=False 参数用于控制内层进度条在完成后是否保留。如果设置为 False，进度条完成后会被清除，以保持输出的简洁性。

4.2 手动更新进度条

有时你可能不会使用一个明确的循环，但仍然需要显示进度条。在这种情况下，你可以手动控制进度条的更新。

from tqdm import tqdm
import time

with tqdm(total=100) as pbar:
    for i in range(10):
        time.sleep(0.5)
        pbar.update(10)

pbar.update(10) 会将进度条推进 10 个单位，总共需要推进到 100。

4.3 与 enumerate 结合

当你需要同时获取索引和元素时，通常会使用 enumerate 函数。tqdm 同样支持与 enumerate 结合使用：

for i, item in enumerate(tqdm(range(100))):
    time.sleep(0.1)

这使得你可以在循环中轻松地跟踪进度，并同时获得索引。

4.4 与 pandas 结合

如果你在处理大型数据集，尤其是使用 pandas 进行数据处理时，tqdm 也能很好地与 pandas 结合。你可以在 apply 函数中添加进度条：

import pandas as pd
from tqdm import tqdm

tqdm.pandas()

df = pd.DataFrame({'a': range(1000)})
df['b'] = df['a'].progress_apply(lambda x: x**2)

通过 tqdm.pandas()，你可以在 pandas 的 apply、map、applymap 等函数中自动添加进度条。

4.5 文件处理进度条

在处理文件时（如读取大文件、下载文件等），tqdm 也可以显示文件处理进度：

from tqdm import tqdm

# 假设你有一个大文件需要逐行读取
with open('large_file.txt', 'r') as f:
    for line in tqdm(f, total=1000000):
        pass  # 处理每一行数据

这里，我们假设文件有 100 万行，通过 tqdm 可以实时监控文件读取的进度。

5. 高级用法

5.1 自定义进度条格式

tqdm 允许你自定义进度条的显示格式。你可以使用 bar_format 参数来控制进度条的外观：

for i in tqdm(range(100), bar_format="{l_bar}{bar}| {n_fmt}/{total_fmt} [{elapsed}<{remaining}, {rate_fmt}{postfix}]"):
    time.sleep(0.1)

在上面的代码中：

• {l_bar} 包含 desc 和百分比。
• {bar} 是进度条本身。
• {n_fmt}/{total_fmt} 显示当前迭代数和总迭代数。
• {elapsed} 是已经耗费的时间。
• {remaining} 是预计的剩余时间。
• {rate_fmt} 是处理速率。

可以根据需求添加或移除这些参数，甚至可以自定义一些新的变量。

5.2 使用装饰器

tqdm 提供了装饰器，用于装饰函数，从而自动为函数调用生成进度条：

from tqdm import tqdm
import time

@tqdm
def my_function():
    for _ in range(100):
        time.sleep(0.1)

my_function()

这样，你可以很方便地为函数添加进度条，而无需显式地在函数内部调用 tqdm。

5.3 GUI 环境中的进度条

如果你是在一个图形用户界面（如 PyQt 或 Tkinter）中工作，而不是命令行，tqdm 也有解决方案。使用 tqdm.gui.tqdm 可以在 GUI 环境中创建进度条。

from tqdm.gui import tqdm
import time

for i in tqdm(range(100)):
    time.sleep(0.1)

tqdm.gui 会自动识别是否运行在 GUI 环境中，并根据环境显示合适的进度条。

5.4 多线程和多进程的进度条

在处理多线程或多进程任务时，tqdm 也支持显示多个任务的进度条。tqdm 通过支持 concurrent.futures 和 multiprocessing 模块来处理并发任务。

from tqdm import tqdm
from concurrent.futures import ThreadPoolExecutor
import time

def task(n):
    time.sleep(n)

with ThreadPoolExecutor(max_workers=10) as executor:
    list(tqdm(executor.map(task, range(10)), total=10))

上面的代码示例使用了 ThreadPoolExecutor 来创建多线程任务，并通过 tqdm 显示每个线程的进度。

5.5 使用 tqdm 处理异步任务

tqdm 也可以与 asyncio 一起使用来处理异步任务。通过 tqdm_asyncio.tqdm_asyncio，你可以轻松地在异步函数中添加进度条。

import asyncio
from tqdm.asyncio import tqdm_asyncio

async def async_task():
    await asyncio.sleep(1)

async def main():
    tasks = [async_task() for _ in range(10)]
    for _ in tqdm_asyncio.as_completed(tasks):
        pass

asyncio.run(main())

这里，tqdm_asyncio.as_completed 可以与 asyncio.as_completed 结合，显示异步任务的进度。

6. 常见问题和优化

6.1 tqdm 与其他库冲突

在某些情况下，tqdm 可能与某些库的输出系统发生冲突，导致进度条显示不正常。例如，logging 模块的输出可能会破坏 tqdm 的进度条。为了解决这个问题，可以将 tqdm 的 write 函数与 logging 结合：

import logging
from tqdm import tqdm

logging.basicConfig(level=logging.INFO)
for i in tqdm(range(100)):
    logging.info("Logging info")

这样，tqdm 会自动处理 logging 的输出，保证进度条的显示不会受到影响。

6.2 性能优化

tqdm 的性能非常好，通常不会成为程序的瓶颈。但如果在非常高频率的更新操作中，进度条的刷新可能会对性能产生一定影响。为了优化性能，可以降低进度条的刷新频率：

for i in tqdm(range(10000), mininterval=1.0):
    time.sleep(0.001)

这里，mininterval=1.0 表示进度条最少每 1 秒刷新一次，而不是每次更新都刷新。

tqdm 是一个强大且易于使用的 Python 库，能够帮助开发者在处理长时间任务时轻松地添加进度条。无论是在简单的循环、复杂的嵌套循环、多线程或异步任务中，tqdm 都提供了丰富的功能来显示进度。此外，它还支持与 pandas、asyncio 等流行库结合，能够适应各种场景下的需求。