from tqdm.auto import tqdm用法详细介绍

tqdm 是一个 Python 库，用于在长时间运行的任务中显示进度条。tqdm.auto 是 tqdm 的一个版本，能够自动适配输出环境（如 Jupyter Notebook、命令行等），以确保进度条在各种环境下显示正确。下面是 tqdm.auto 的详细用法介绍及示例。

1.tqdm.auto 的基本用法

1. 基础用法
   tqdm 可以很方便地用于显示循环的进度条。

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

   上面代码会显示一个进度条，每次循环迭代时进度条都会更新，直到任务完成。
   

2. 使用在函数中
   你可以将 tqdm 应用于任何可迭代对象，包括列表、生成器等。

   from tqdm.auto import tqdm
   import time
   
   def process_data(data):
       for item in tqdm(data):
           time.sleep(0.1)  # 模拟数据处理
   data = range(50)
   process_data(data)
   

3. 自定义进度条参数
   tqdm 允许定制进度条的显示格式，包括进度条的描述、步长、刷新率等。

   from tqdm.auto import tqdm
   import time
   
   for i in tqdm(range(100), desc="Processing", unit="iter", ncols=100, colour="green"):
       time.sleep(0.05)  # 模拟一个耗时操作
   

参数解释：

• desc: 进度条的描述文字，默认不显示。
• unit: 步长单位，默认是 ‘it’。
• ncols: 进度条的宽度，单位为字符。
• colour: 进度条的颜色，默认颜色由环境决定。

4. 嵌套进度条
   当处理嵌套循环时，可以使用多层 tqdm 进度条。

from tqdm.auto import tqdm
import time

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

外层循环会显示为一个外部进度条，而内层循环的进度条会显示为内部的子进度条。

5. 手动更新进度条
   对于不使用循环的情况，也可以手动更新进度条。

from tqdm.auto import tqdm
import time

progress_bar = tqdm(total=100)
for i in range(10):
  time.sleep(0.5)  
  progress_bar.update(10) # 以10%的速度更新进度条
progress_bar.close()

• total: 进度条的总数目。
• update(n): 手动增加进度条的进度，n 是步长。
  

6. 结合 Pandas
   tqdm 可以结合 Pandas 显示进度条，例如在 apply 或 groupby 操作中。

import pandas as pd
from tqdm.auto import tqdm

tqdm.pandas()  # 启用 tqdm for pandas

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

7. 结合文件下载
   tqdm 也可以用于显示文件下载进度。

import requests
from tqdm.auto import tqdm

url = "https://example.com/largefile.zip"
response = requests.get(url, stream=True)
total_size = int(response.headers.get('content-length', 0))

with open("largefile.zip", 'wb') as file, tqdm(
    desc="Downloading", total=total_size, unit='B', unit_scale=True, unit_divisor=1024
) as bar:
    for data in response.iter_content(chunk_size=1024):
        file.write(data)
        bar.update(len(data))

2. tqdm 常见入参

1. iterable: 任何可迭代对象，如 range()、列表、生成器等。

   • 类型: iterable
   • 默认值: None
   • 说明: 表示需要显示进度条的对象。

2. desc: 进度条左侧的描述文字。

   • 类型: str
   • 默认值: None
   • 说明: 为进度条加上说明文本，可以用于描述当前任务。

   tqdm(range(100), desc="Loading")
   

3. total: 迭代的总步数。

   • 类型: int
   • 默认值: None
   • 说明: 如果没有提供可迭代对象（即手动更新进度），需要指定总步数。

   tqdm(total=100)
   

4. leave: 是否在任务完成后保留进度条。

   • 类型: bool
   • 默认值: True
   • 说明: True 表示任务完成后进度条保持在屏幕上；False 表示任务完成后清除进度条。

   tqdm(range(100), leave=False)
   

5. ncols: 进度条的宽度（字符数）。

   • 类型: int
   • 默认值: None（自动调整宽度）
   • 说明: 控制进度条在屏幕上显示的宽度。

   tqdm(range(100), ncols=80)
   

6. mininterval: 最小刷新间隔时间（秒）。

   • 类型: float
   • 默认值: 0.1
   • 说明: 控制进度条刷新的最小时间间隔，避免过于频繁刷新，减少系统开销。

   tqdm(range(100), mininterval=0.5)
   

7. maxinterval: 最大刷新间隔时间（秒）。

   • 类型: float
   • 默认值: 10
   • 说明: 设置进度条的最大刷新间隔时间。如果任务较长，可以设定一个上限，以确保定期刷新。

   tqdm(range(100), maxinterval=5)
   

8. miniters: 最小更新步数。

   • 类型: int or float
   • 默认值: 1
   • 说明: 控制进度条更新的最小步长。例如，每 10 步才刷新一次。

   tqdm(range(100), miniters=10)
   

9. ascii: 使用 ASCII 字符显示进度条（适用于不支持 Unicode 的终端）。

   • 类型: bool or str
   • 默认值: False
   • 说明: 使用 True 时，会用 ASCII 字符显示进度条。你也可以传入自定义的字符序列。

   tqdm(range(100), ascii=True)
   

10. disable: 禁用进度条。

    • 类型: bool
    • 默认值: False
    • 说明: 设置为 True 时，禁用进度条（例如用于不需要显示进度条的环境中）。

    tqdm(range(100), disable=True)
    

11. unit: 进度条步长单位。

    • 类型: str
    • 默认值: 'it'
    • 说明: 用于指示进度条的单位，例如字节、行、项等。

    tqdm(range(100), unit="B")
    

12. unit_scale: 是否自动缩放单位。

    • 类型: bool or int or float
    • 默认值: False
    • 说明: 设置为 True 时，自动调整单位，如 1024 -> 1K。可以手动指定缩放倍数。

    tqdm(range(10000), unit_scale=True)
    

13. unit_divisor: 单位缩放的基数。

    • 类型: int
    • 默认值: 1000
    • 说明: 控制单位缩放时的除数，常用于字节单位显示（如 1024）。

    tqdm(range(10000), unit="B", unit_scale=True, unit_divisor=1024)
    

14. dynamic_ncols: 动态调整进度条宽度。

    • 类型: bool
    • 默认值: True
    • 说明: 进度条会根据终端窗口宽度动态调整长度。

    tqdm(range(100), dynamic_ncols=True)
    

15. smoothing: 平滑速度的系数。

    • 类型: float
    • 默认值: 0.3
    • 说明: 用于计算平均速度的平滑因子，数值越小，更新越灵敏。

    tqdm(range(100), smoothing=0.1)
    

16. colour: 设置进度条颜色。

    • 类型: str
    • 默认值: None
    • 说明: 可以设置进度条的颜色，例如 'green'。

    tqdm(range(100), colour="green")
    

示例代码

from tqdm.auto import tqdm
import time

for i in tqdm(range(100), desc="Processing", total=100, unit="iter", ncols=100, leave=False, mininterval=0.5, ascii=True, colour="blue"):
    time.sleep(0.05)

通过这些参数，tqdm 可以非常灵活地定制进度条的显示方式。