trace --- ردگیری یا پیگیری اجرای دستورات پایتون¶
کد منبع: Lib/trace.py
ماژول trace به شما امکان میدهد اجرای برنامه را ردگیری کنید، فهرستهای پوشش دستورهای حاشیهنویسیشده تولید کنید، روابط فراخواننده/فراخوانده را چاپ کنید و توابع اجراشده در طول اجرای برنامه را فهرست کنید. میتوان از آن در برنامهای دیگر یا از خط فرمان استفاده کرد.
همچنین ملاحظه نمائید
- Coverage.py
یک ابزار پوشش محبوب شخص ثالث که خروجی HTML را به همراه قابلیتهای پیشرفتهای مانند پوشش شاخه ارائه میدهد.
استفاده از خط فرمان¶
میتوان ماژول trace را از خط فرمان فراخوانی کرد. این کار میتواند به سادگی زیر باشد
python -m trace --count -C . somefile.py ...
مورد بالا somefile.py را اجرا خواهد کرد و فهرستهای حاشیهنویسیشدهای از همهی ماژولهای پایتونی که در حین اجرا ایمپورت میشوند را در پوشهی جاری تولید خواهد کرد.
- --help¶
نمایش کاربرد و خروج.
- --version¶
نمایش نسخهی ماژول و خروج.
اضافه شده در نسخهی 3.8: گزینه --module افزوده شد که امکان اجرای یک ماژول اجرایی را فراهم میکند.
گزینههای اصلی¶
حداقل یکی از گزینههای زیر باید هنگام فراخوانی trace مشخص شود. گزینه --listfuncs با گزینههای --trace و --count متقابلاً ناسازگار است. وقتی --listfuncs ارائه شود، نه --count و نه --trace پذیرفته نمیشوند، و بالعکس.
- -c, --count¶
تولید مجموعهای از پروندههای فهرست حاشیهنویسیشده پس از تکمیل برنامه، که نشان میدهد هر دستور چند بار اجرا شده است. همچنین در ادامه
--coverdir،--fileو--no-reportرا ببینید.
- -t, --trace¶
سطرها را همانطور که اجرا میشوند، نمایش دهید.
- -l, --listfuncs¶
نمایش توابع اجراشده با اجرای برنامه.
- -r, --report¶
یک فهرست حاشیهنویسیشده از اجرای قبلی برنامه که از گزینههای
--countو--fileاستفاده کرده است، تولید کنید. این کار هیچ کدی را اجرا نمیکند.
- -T, --trackcalls¶
روابط فراخوانی نمایانشده با اجرای برنامه را نمایش دهید.
اصلاحکنندهها¶
- -f, --file=<file>¶
نام پروندهای برای انباشتن شمارشها در چندین اجرای ردگیری. باید همراه با گزینهی
--countاستفاده شود.
- -C, --coverdir=<dir>¶
پوشهای که پروندههای گزارش در آن قرار میگیرند. گزارش پوشش برای
package.moduleدر پروندهdir/package/module.coverنوشته میشود.
- -m, --missing¶
هنگام تولید فهرستهای حاشیهنویسیشده، سطرهایی را که اجرا نشدهاند با
>>>>>>علامتگذاری کنید.
- -s, --summary¶
هنگام استفاده از
--countیا--report، برای هر پرونده پردازششده خلاصهای کوتاه در stdout نوشته میشود.
- -R, --no-report¶
فهرستهای حاشیهنویسیشده را تولید نکنید. این زمانی مفید است که قصد دارید چندین اجرا با
--countانجام دهید و سپس یک مجموعه واحد از فهرستهای حاشیهنویسیشده را در پایان تولید کنید.
- -g, --timing¶
هر خط را با زمان سپریشده از آغاز برنامه پیشوند کنید. فقط هنگام ردگیری استفاده میشود.
فیلترها¶
این گزینهها را میتوان چندین بار تکرار کرد.
- --ignore-module=<mod>¶
هر یک از نامهای ماژول دادهشده و زیرماژولهای آن (اگر بسته باشد) را نادیده بگیرید. آرگومان میتواند فهرستی از نامها باشد که با کاما از هم جدا شدهاند.
- --ignore-dir=<dir>¶
تمام ماژولها و بستهها را در پوشهی مشخصشده و زیرپوشهها نادیده بگیرید. آرگومان میتواند فهرستی از پوشهها باشد که با
os.pathsepجدا شدهاند.
رابط برنامهای¶
- class trace.Trace(count=1, trace=1, countfuncs=0, countcallers=0, ignoremods=(), ignoredirs=(), infile=None, outfile=None, timing=False)¶
یک شیء برای ردگیری اجرای یک دستور یا عبارت ایجاد کنید. تمام پارامترها اختیاری هستند. count شمارش شمارههای خط را فعال میکند. trace ردگیری اجرای سطرها را فعال میکند. countfuncs فهرستگیری از توابعی که در طول اجرا فراخوانی میشوند را فعال میکند. countcallers پیگیری روابط فراخوانی را فعال میکند. ignoremods فهرستی از ماژولها یا بستههایی است که باید نادیده گرفته شوند. ignoredirs فهرستی از پوشههایی است که ماژولها یا بستههای آنها باید نادیده گرفته شوند. infile نام پروندهای است که اطلاعات شمارش ذخیرهشده از آن خوانده میشود. outfile نام پروندهای است که اطلاعات شمارش بهروز شده در آن نوشته میشود. timing نمایش یک مهر زمانی نسبت به زمان آغاز ردگیری را فعال میکند.
- run(cmd)¶
دستور را اجرا کنید و آمار را از اجرا با پارامترهای ردگیری فعلی جمعآوری کنید. cmd باید یک رشته یا شیء کد باشد، مناسب برای ارسال به
exec().
- runctx(cmd, globals=None, locals=None)¶
فرمان را اجرا کنید و آمار حاصل از اجرا را با پارامترهای ردگیری جاری، در محیطهای سراسری و محلی تعریفشده جمعآوری کنید. اگر تعریفنشده باشند، globals و locals بهطور پیشفرض دیکشنریهای خالی خواهند بود.
- runfunc(func, /, *args, **kwds)¶
func را با آرگومانهای دادهشده، تحت کنترل شیء
Traceبا پارامترهای ردگیری کنونی فراخوانی کنید.
- results()¶
یک شیء
CoverageResultsرا برمیگرداند که شامل نتایج تجمعی تمام فراخوانیهای پیشینrun،runctxوrunfuncبرای نمونهیTraceدادهشده است. نتایج ردگیری انباشتهشده را بازنشانی نمیکند.
- class trace.CoverageResults¶
ظرفی برای نتایج پوشش، که توسط
Trace.results()ایجاد میشود. نباید بهصورت مستقیم توسط کاربر ایجاد شود.- update(other)¶
دادهها را از یک شیء
CoverageResultsدیگر ادغام کنید.
- write_results(show_missing=True, summary=False, coverdir=None, *, ignore_missing_files=False)¶
نتایج پوشش را مینویسد. برای نمایش سطرهایی که هیچ برخوردی نداشتند، show_missing را تنظیم کنید. برای گنجاندن خلاصه پوشش به تفکیک ماژول در خروجی، summary را تنظیم کنید. coverdir پوشهای را مشخص میکند که پروندههای نتایج پوشش در آن خروجی داده میشوند. اگر
Noneباشد، نتایج هر پرونده منبع در پوشه خودش قرار میگیرند.اگر ignore_missing_files برابر
Trueباشد، شمارشهای پوشش برای پروندههایی که دیگر وجود ندارند، بهصورت بیصدا نادیده گرفته میشوند. در غیر این صورت، یک پرونده ناموجود باعث پرتابFileNotFoundErrorمیشود.تغییر یافته در نسخهی 3.13: پارامتر ignore_missing_files افزوده شد.
یک مثال ساده برای نشان دادن استفاده از رابط برنامهنویسی:
import sys
import trace
# create a Trace object, telling it what to ignore, and whether to
# do tracing or line-counting or both.
tracer = trace.Trace(
ignoredirs=[sys.prefix, sys.exec_prefix],
trace=0,
count=1)
# run the new command using the given tracer
tracer.run('main()')
# make a report, placing output in the current directory
r = tracer.results()
r.write_results(show_missing=True, coverdir=".")