استفاده از tqdm برای نمایش Progress Bar در پایتون

در بسیاری از موارد در هنگام برنامه‌نویسی با پایتون، به خصوص زمانی که با حلقه‌های طولانی و پردازش‌های زمان‌بر سر و کار داریم، نیاز به نمایش پیشرفت کار به کاربر احساس می‌شود. این کار نه تنها به کاربر اطمینان می‌دهد که برنامه در حال کار است، بلکه به او کمک می‌کند تا تخمین بزند چه مدت زمان دیگری تا پایان کار باقی مانده است. کتابخانه tqdm یک راه حل ساده و قدرتمند برای افزودن نوار پیشرفت (Progress Bar) به برنامه‌های پایتونی شما ارائه می‌دهد.

مقدمه‌ای بر tqdm

tqdm مخفف “taqaddum” (تقدّم) است که یک کلمه عربی به معنای پیشرفت است. این کتابخانه به شما امکان می‌دهد تا به راحتی نوار پیشرفت را به حلقه‌ها، تکراتورها و سایر اشیاء قابل تکرار در پایتون اضافه کنید. tqdm به طور خودکار زمان تخمینی باقی‌مانده، سرعت پردازش و درصد پیشرفت را محاسبه و نمایش می‌دهد.

نصب tqdm

برای استفاده از tqdm، ابتدا باید آن را نصب کنید. این کار را می‌توانید با استفاده از pip انجام دهید:

pip install tqdm

استفاده ساده از tqdm با حلقه‌ها

ساده‌ترین راه برای استفاده از tqdm، استفاده از آن در یک حلقه for است. به عنوان مثال:

from tqdm import tqdm
import time

for i in tqdm(range(100)):
    time.sleep(0.01) # شبیه‌سازی یک پردازش زمان‌بر

در این مثال، tqdm(range(100)) یک تکراتور را برمی‌گرداند که با حلقه for تکرار می‌شود. tqdm به طور خودکار نوار پیشرفت را در ترمینال نمایش می‌دهد و با پیشرفت حلقه، آن را به‌روزرسانی می‌کند.

تنظیمات پیشرفته tqdm

tqdm گزینه‌های مختلفی را برای سفارشی‌سازی نوار پیشرفت ارائه می‌دهد. برخی از مهم‌ترین این گزینه‌ها عبارتند از:

• desc: یک رشته برای نمایش توضیحات در کنار نوار پیشرفت.
• total: تعداد کل تکرارها. اگر این مقدار مشخص نشود، tqdm سعی می‌کند آن را به طور خودکار تشخیص دهد.
• leave: اگر True باشد (مقدار پیش‌فرض)، نوار پیشرفت پس از اتمام کار در ترمینال باقی می‌ماند. اگر False باشد، نوار پیشرفت حذف می‌شود.
• unit: واحد اندازه‌گیری پیشرفت. به عنوان مثال، “it” برای تکرار، “B” برای بایت، “KB” برای کیلوبایت و غیره.
• unit_scale: اگر True باشد، واحد اندازه‌گیری به طور خودکار مقیاس‌بندی می‌شود (به عنوان مثال، از بایت به کیلوبایت و غیره).
• unit_divisor: مقداری که برای مقیاس‌بندی واحد اندازه‌گیری استفاده می‌شود.
• bar_format: یک رشته برای سفارشی‌سازی قالب نوار پیشرفت.

مثال:

from tqdm import tqdm
import time

for i in tqdm(range(100), desc="Processing", total=100, leave=False, unit="step", unit_scale=True):
    time.sleep(0.01)

در این مثال، نوار پیشرفت با توضیحات “Processing” نمایش داده می‌شود، تعداد کل تکرارها 100 است، پس از اتمام کار حذف می‌شود، واحد اندازه‌گیری “step” است و واحد اندازه‌گیری به طور خودکار مقیاس‌بندی می‌شود.

استفاده از tqdm با تکراتورها

tqdm را می‌توان با هر نوع تکراتوری استفاده کرد، نه فقط حلقه‌های for. به عنوان مثال:

from tqdm import tqdm
import time

my_iterator = iter(range(100))

for i in tqdm(my_iterator, desc="Iterating"):
    time.sleep(0.01)

در این مثال، tqdm با تکراتور my_iterator استفاده می‌شود.

استفاده از tqdm در توابع

برای استفاده از tqdm در یک تابع، می‌توانید تابع را با tqdm بپوشانید. به عنوان مثال:

from tqdm import tqdm
import time

def my_function(data):
    for item in tqdm(data, desc="Processing data"):
        time.sleep(0.01)
        # انجام پردازش بر روی item

my_data = range(100)
my_function(my_data)

در این مثال، تابع my_function با tqdm پوشانده شده است. این باعث می‌شود که نوار پیشرفت در هنگام اجرای تابع نمایش داده شود.

استفاده از tqdm با فایل‌ها

tqdm می‌تواند برای نمایش پیشرفت خواندن یا نوشتن فایل‌ها نیز استفاده شود. به عنوان مثال:

from tqdm import tqdm

file_size = 1024 * 1024 * 100 # 100MB
with tqdm(total=file_size, unit="B", unit_scale=True, desc="Reading file") as pbar:
    with open("my_file.txt", "rb") as f:
        while True:
            chunk = f.read(4096)
            if not chunk:
                break
            pbar.update(len(chunk))

در این مثال، tqdm برای نمایش پیشرفت خواندن فایل my_file.txt استفاده می‌شود. total برابر با اندازه فایل است، unit برابر با “B” (بایت) است، unit_scale برابر با True است و desc برابر با “Reading file” است. تابع update برای به‌روزرسانی نوار پیشرفت با مقدار داده‌های خوانده شده استفاده می‌شود.

استفاده از tqdm در محیط‌های چند پردازشی

tqdm به طور پیش‌فرض برای استفاده در محیط‌های تک پردازشی طراحی شده است. با این حال، می‌توان از آن در محیط‌های چند پردازشی نیز استفاده کرد، اما نیاز به کمی پیکربندی اضافی دارد. برای این کار، می‌توانید از کلاس tqdm.contrib.concurrent.process_map استفاده کنید.

from tqdm.contrib.concurrent import process_map
import time

def my_function(x):
    time.sleep(0.1)
    return x * 2

if __name__ == '__main__':
    results = process_map(my_function, range(100), max_workers=4, desc="Processing")
    print(results)

در این مثال، process_map تابع my_function را به صورت موازی بر روی عناصر range(100) اعمال می‌کند. max_workers تعداد پردازشگرهایی را که باید استفاده شوند را مشخص می‌کند و desc توضیحات نوار پیشرفت را تعیین می‌کند.

نکات و ترفندها

• برای جلوگیری از تداخل نوار پیشرفت با خروجی‌های دیگر، می‌توانید از پارامتر file در tqdm استفاده کنید تا نوار پیشرفت را به یک فایل خاص هدایت کنید.
• اگر می‌خواهید نوار پیشرفت را به صورت دستی به‌روزرسانی کنید، می‌توانید از متد update استفاده کنید.
• برای نمایش اطلاعات اضافی در کنار نوار پیشرفت، می‌توانید از پارامتر postfix استفاده کنید.

نتیجه‌گیری

tqdm یک کتابخانه قدرتمند و آسان برای استفاده است که به شما امکان می‌دهد تا به راحتی نوار پیشرفت را به برنامه‌های پایتونی خود اضافه کنید. این کار نه تنها تجربه کاربری را بهبود می‌بخشد، بلکه به شما کمک می‌کند تا عملکرد برنامه‌های خود را بهتر درک کنید. با استفاده از گزینه‌های مختلف سفارشی‌سازی tqdm، می‌توانید نوار پیشرفت را به طور کامل با نیازهای خود تنظیم کنید.