معرفی کتابخانه trace در پایتون

کتابخانهٔ استاندارد trace در پایتون ابزاری برای ردگیری اجرای کدهای پایتون است. این ماژول متکی بر sys.settrace() بوده و به شما امکان می‌دهد تا اجرای هر خط از برنامه را ثبت کنید یا پوشش (coverage) خطوط اجراشده را تولید کنید. از کاربردهای رایج آن می‌توان به دیباگ دقیق، تحلیل پوشش تست‌ها، و ساخت گزارشات خط به خط اشاره کرد.

ویژگی‌های اصلی

• ردگیری اجرای هر خط (line tracing)
• شمارش تعداد اجراهای هر خط (coverage counting)
• ایجاد فایل‌های گزارش پوشش برای تحلیل
• قابلیت فیلتر کردن ماژول‌ها و پوشه‌ها برای کاهش نویز
• قابل استفاده هم به‌صورت API و هم از طریق اجرای ماژول با python -m trace

پارامترهای مهم Trace

مثال پایه‌ای: تولید گزارش پوشش (coverage)

import sys
from trace import Trace

def fib(n):
    if n <= 1:
        return n
    return fib(n-1) + fib(n-2)

def main():
    print(fib(5))

if __name__ == '__main__':
    tracer = Trace(count=True, trace=False,
                   ignoremods=('builtins',),
                   ignoredirs=[sys.prefix, sys.exec_prefix])
    tracer.run('main()')
    results = tracer.results()
    results.write_results(show_missing=True, coverdir='cover')

در این کد یک نمونه از Trace ساخته می‌شود که تنها شمارش پوشش را فعال کرده است (count=True) و خودِ نمایش خط به خط را غیرفعال کرده (trace=False). با استفاده از ignoremods و ignoredirs تلاش شده تا کتابخانه‌های استاندارد و توابع داخلی نادیده گرفته شوند. سپس با tracer.run('main()') تابع اصلی اجرا و نتایج با write_results در پوشهٔ cover ذخیره می‌شود. فایل‌های تولیدشده می‌توانند برای تحلیل پوشش کد توسط ابزارهای دیگر بازخوانی شوند.

توضیح بیشتر دربارهٔ write_results

متد results.write_results(show_missing=True, coverdir='cover') فایل‌هایی از نوع «.cover» تولید می‌کند که هر یک حاوی شمارش اجراهای خطوط منبع هستند و می‌توان با اسکریپت‌ها یا پردازش دستی آن‌ها را تحلیل نمود. گزینهٔ show_missing=True باعث می‌شود خطوطی که اجرا نشده‌اند هم در گزارش مشخص شوند.

استفاده از trace به‌صورت خط فرمان

ماژول trace را می‌توان با گزینه‌هایی از طریق خط فرمان اجرا کرد. نمونه:

python -m trace --count --summary myscript.py

گزینهٔ --count شمارش پوشش را فعال می‌کند و --summary گزارش خلاصه‌ای از پوشش تولید می‌کند. همچنین می‌توانید از --trace برای چاپ هر خط اجراشونده استفاده کنید؛ این حالت برای دیباگ گام‌به‌گام مفید است ولی خروجی بسیار پرحجمی تولید می‌کند.

مثال پیشرفته: ترکیب با محیط تست

یکی از موارد کاربردی، اجرای تست‌ها (برای مثال از unittest) تحت رجیستری trace و پس از آن تولید گزارش پوشش است. رویکرد معمول این است که بستهٔ تست را از طریق یک اسکریپت احاطه کرده و سپس نتایج را جمع‌آوری کنید.

مثال: اجرای تابع با کانتکستِ دلخواه

from trace import Trace

def do_work(x):
    return x * 2

tracer = Trace(count=True)
# اجرای عبارت در کانتکست مشخص
tracer.runctx('result = do_work(10)', globals(), locals())
res = tracer.results()
res.write_results(show_missing=True, coverdir='cover')

در این مثال از runctx استفاده شده تا عبارت مورد نظر در کانتکست مشخصی اجرا شود. این حالت زمانی مفید است که بخواهید متغیرهای محیطی یا ماژول‌های خاصی را قبل از اجرا تنظیم کنید.

نکات پیشرفته و محدودیت‌ها

• trace فقط کد پایتون را می‌بیند؛ فراخوانی‌های پیاده‌سازی‌شده در C (مانند بخش‌هایی از برخی ماژول‌ها) توسط trace قابل مشاهده نیستند.
• استفاده از trace باعث کاهش چشمگیر کارایی می‌شود؛ برای تحلیل‌های حجیم بهتر است نمونه‌برداری یا ابزارهای پوشش اختصاصی (مثل coverage.py) را بررسی کنید.
• فرایندهای جدید (subprocess) یا threadهای جداگانه به‌طور پیش‌فرض ردیابی نمی‌شوند مگر اینکه خودتان صحنه را تنظیم کنید.
• برای کاهش نویز گزارش، حتماً ignoredirs و ignoremods را به درستی پیکربندی کنید تا فقط کد مورد نظر شما بررسی شود.

مقایسهٔ کوتاه با ابزارهای پوشش حرفه‌ای

ابزارهایی مانند coverage.py قابلیت‌های بیشتری مانند ادغام با ابزارهای CI، نمایش گرافیکی و پلاگین‌های متنوع دارند. اما کتابخانهٔ trace مزیت سادگی و درونی بودن به‌عنوان یک ماژول استاندارد را دارد و برای تحلیل سریع و نمونه‌های آموزشی بسیار مناسب است.

جمع‌بندی و توصیه‌ها

کتابخانهٔ trace یک ابزار سبک و مفید برای ردیابی خط به خط و تولید گزارش پوشش اولیه است. برای استفادهٔ موثر:

• قبل از اجرا، ignoredirs و ignoremods را تنظیم کنید.
• در فرآیندهای حجیم یا تولیدی از ابزارهای بهینه‌شده‌تر استفاده کنید.
• از حالت trace برای دیباگ خطی استفاده کنید و از count برای پوشش.

در صورت نیاز می‌توان مثال‌هایی خاص برای پروژه یا ترکیب با ابزارهای تست/CICD ارائه داد تا خروجی متناسب با نیاز شما تولید شود.

لطفاً از کمبود ها و مشکلات این محتوا برای ما بنویسید

ارسال