pstats --- آمار برای پروفایل‌گیرها¶
کد منبع: Lib/pstats.py
ماژول pstats ابزارهایی را برای خواندن، دستکاری و نمایش آمارهای پروفایل‌گیری تولیدشده توسط پروفایل‌گیرهای پایتون فراهم می‌کند. این ماژول خروجی هر دو ماژول profiling.tracing (پروفایل‌گیر قطعی) و profiling.sampling (پروفایل‌گیر آماری) را می‌خواند.
خواندن و نمایش داده‌های پروفایل¶
کلاس Stats رابط اصلی برای کار با داده‌های پروفایل است. این کلاس می‌تواند آمار را از پرونده‌ها یا مستقیماً از یک شیء Profile بخواند.
بارگذاری آمار از یک پرونده و چاپ یک گزارش پایه‌ای:
import pstats
p = pstats.Stats('profile_output.prof')
p.print_stats()
شیء Stats متدهایی را برای مرتب‌سازی و فیلتر کردن داده‌ها قبل از چاپ فراهم می‌کند. برای مثال، برای مشاهده‌ی ده تابع با بیشترین زمان انباشته:
from pstats import SortKey
p = pstats.Stats('profile_output.prof')
p.sort_stats(SortKey.CUMULATIVE).print_stats(10)
کار با آمار¶
کلاس Stats از زنجیره‌سازی متدها پشتیبانی می‌کند و انجام چندین عملیات را به شکلی ساده فراهم می‌سازد:
p = pstats.Stats('restats')
p.strip_dirs().sort_stats(-1).print_stats()
متد strip_dirs() مسیرهای پوشه را از نام پرونده‌ها حذف می‌کند و خروجی را فشرده‌تر می‌سازد. متد sort_stats() کلیدهای مختلفی را برای کنترل ترتیب مرتب‌سازی می‌پذیرد.
کلیدهای مرتب‌سازی مختلف، جنبه‌های متفاوتی از عملکرد را برجسته می‌کنند:
from pstats import SortKey
# توابعی که بیشترین زمان انباشته را مصرف می‌کنند
p.sort_stats(SortKey.CUMULATIVE).print_stats(10)
# توابعی که بیشترین زمان را در کد خودشان مصرف می‌کنند
p.sort_stats(SortKey.TIME).print_stats(10)
# توابع مرتب‌شده بر اساس نام
p.sort_stats(SortKey.NAME).print_stats()
فیلتر کردن خروجی¶
متد print_stats() محدودیت‌هایی را می‌پذیرد که مشخص می‌کنند چه توابعی نمایش داده شوند. محدودیت‌ها می‌توانند عدد صحیح (محدود کردن تعداد)، عدد اعشاری بین ۰ و ۱ (انتخاب یک درصد)، یا رشته (تطبیق نام توابع از طریق عبارت باقاعده) باشند.
چاپ فقط ۱۰ درصد برتر:
p.print_stats(.1)
چاپ فقط توابعی که نام آن‌ها شامل "init" است:
p.print_stats('init')
ترکیب محدودیت‌ها (به‌صورت پیاپی اعمال می‌شوند):
# Top 10%, then only those containing "init"
p.print_stats(.1, 'init')
# Functions in files matching "foo:", limited to top 50%
p.sort_stats(SortKey.FILENAME).print_stats('foo:', .5)
تحلیل روابط فراخوانی¶
متد print_callers() نشان می‌دهد که کدام تابع‌ها هر تابع نمایش‌داده‌شده را فراخوانی کرده‌اند:
p.print_callers()
متد print_callees() رابطه‌ی متقابل را نشان می‌دهد و فهرست می‌کند که هر تابع نمایش‌داده‌شده کدام تابع‌ها را فراخوانی کرده است:
p.print_callees()
هر دو متد همان آرگومان‌های محدودیت را می‌پذیرند که متد print_stats() می‌پذیرد.
ترکیب چند پروفایل¶
آمار حاصل از چندین اجرای پروفایل‌گیری را می‌توان در یک شیء Stats واحد ترکیب کرد:
# Load multiple files at once
p = pstats.Stats('run1.prof', 'run2.prof', 'run3.prof')
# Or add files incrementally
p = pstats.Stats('run1.prof')
p.add('run2.prof')
p.add('run3.prof')
هنگامی که پرونده‌ها ترکیب می‌شوند، آمار مربوط به توابع یکسان (پرونده، سطر و نام یکسان) انباشته می‌شوند و نمای تجمیعی از تمامی اجراهای پروفایل‌گیری ارائه می‌دهند.
کلاس Stats¶
- class pstats.Stats(*filenames_or_profile, stream=sys.stdout)¶
ایجاد یک شیء آماری از داده‌های پروفایل.
آرگومان‌ها می‌توانند نام پرونده‌ها (رشته‌ها یا اشیای شبه‌مسیر) یا اشیای
Profileباشند. اگر چندین منبع ارائه شود، آمار آن‌ها با یکدیگر ترکیب می‌شود.آرگومان stream مشخص می‌کند که خروجی متد
print_stats()و متدهای مرتبط با آن در کجا نوشته شود. مقدار پیش‌فرض آنsys.stdoutاست.قالب داده‌های پروفایل مختص نسخه‌ای از پایتون است که آن را ایجاد کرده است. هیچ تضمینی برای سازگاری بین نسخه‌های مختلف پایتون یا بین پروفایل‌گیرهای مختلف وجود ندارد.
- strip_dirs()¶
حذف اطلاعات مسیر پیشرو از تمام نام‌پرونده‌ها.
این متد شیء را در جای خود اصلاح می‌کند و آن را برای زنجیره‌سازی متدها برمی‌گرداند. پس از حذف، آمار به‌صورت دارای ترتیب تصادفی در نظر گرفته می‌شود.
اگر حذف باعث شود دو تابع غیرقابل‌تمایز شوند (نام‌پرونده، شماره سطر و نام تابع یکسان)، آمار آن‌ها در یک درایه‌ی واحد ترکیب می‌شود.
- add(*filenames)¶
اضافه کردن داده‌های پروفایل‌گیری از پرونده‌های اضافی.
پرونده‌ها باید توسط همان نوع پروفایل‌گیر ایجاد شده باشند. آمارهای مربوط به توابع یکسان انباشته می‌شوند.
- dump_stats(filename)¶
ذخیره‌سازی آمارهای فعلی در یک پرونده.
اگر پرونده وجود نداشته باشد ایجاد می‌شود و اگر وجود داشته باشد، روی آن نوشته می‌شود. داده‌های ذخیره‌شده را می‌توان با ایجاد یک شیء جدید از
Statsبارگذاری کرد.
- sort_stats(*keys)¶
مرتب‌سازی آمارها بر اساس معیارهای مشخص‌شده.
هر کلید می‌تواند یک رشته یا یکی از اعضای شمارشی
SortKeyباشد. هنگامی که چندین کلید ارائه می‌شود، کلیدهای بعدی تساوی‌های کلیدهای قبلی را می‌شکنند.استفاده از اعضای شمارشی
SortKeyبه دلیل فراهم کردن بررسی خطای بهتر، به رشته‌ها ترجیح داده می‌شود:from pstats import SortKey p.sort_stats(SortKey.CUMULATIVE)
کلیدهای مرتب‌سازی معتبر:
رشته
Enum
معنی
'calls'SortKey.CALLSتعداد فراخوانی‌ها
'cumulative'SortKey.CUMULATIVEزمان تجمعی
'cumtime'ناموجود
زمان تجمعی
'file'ناموجود
نام پرونده
'filename'SortKey.FILENAMEنام پرونده
'module'ناموجود
نام پرونده
'ncalls'ناموجود
تعداد فراخوانی‌ها
'pcalls'SortKey.PCALLSتعداد فراخوانی‌های اولیه
'line'SortKey.LINEشماره‌ی سطر
'name'SortKey.NAMEنام تابع
'nfl'SortKey.NFLنام/پرونده/سطر
'stdname'SortKey.STDNAMEنام استاندارد
'time'SortKey.TIMEزمان داخلی
'tottime'ناموجود
زمان داخلی
تمام مرتب‌سازی‌ها روی آمار به ترتیب نزولی هستند (زمان‌برترین‌ها در ابتدا)، در حالی که مرتب‌سازی‌های نام، پرونده و شماره‌سطر صعودی (الفبایی) هستند.
تفاوت بین
SortKey.NFLوSortKey.STDNAMEدر این است که NFL شماره‌سطرها را به صورت عددی مرتب می‌کند، در حالی که STDNAME آن‌ها را به عنوان رشته مرتب می‌کند. عبارتsort_stats(SortKey.NFL)معادلsort_stats(SortKey.NAME, SortKey.FILENAME, SortKey.LINE)است.برای سازگاری عقبگرد، آرگومان‌های عددی
-1،0،1و2نیز پذیرفته می‌شوند که به ترتیب به معنای'stdname'،'calls'،'time'و'cumulative'هستند.اضافه شده در نسخه‌ی 3.7: شمارشی (enum) از
SortKey.
- reverse_order()¶
معکوس کردن ترتیب مرتب‌سازی فعلی.
به طور پیش‌فرض، جهت مرتب‌سازی به صورت مناسب برای کلید مرتب‌سازی انتخاب می‌شود (نزولی برای کلیدهای مبتنی بر زمان، صعودی برای کلیدهای مبتنی بر نام). این متد آن انتخاب را معکوس می‌کند.
- print_stats(*restrictions)¶
چاپ گزارشی از آمارهای پروفایل‌گیری.
خروجی شامل یک سطر سرآیند که داده‌ها را خلاصه می‌کند، به همراه جدول آمارهای توابع است که بر اساس آخرین فراخوانی
sort_stats()مرتب شده‌اند.محدودیت‌ها خروجی را فیلتر می‌کنند. هر محدودیت یکی از موارد زیر است:
یک عدد صحیح: خروجی را به آن تعداد مدخل محدود می‌کند
یک عدد اعشاری بین 0.0 و 1.0: آن کسری از مدخل‌ها را انتخاب می‌کند
یک رشته: نام توابع را از طریق عبارت باقاعده مطابقت می‌دهد
محدودیت‌ها به صورت ترتیبی اعمال می‌شوند. برای مثال:
print_stats(.1, 'foo:')
ابتدا به ۱۰ درصد برتر محدود می‌کند، سپس روی توابعی که با 'foo:' مطابقت دارند فیلتر می‌کند.
- print_callers(*restrictions)¶
چاپ کردن فراخواننده‌های هر تابع در آمار.
برای هر تابع در نتایج فیلترشده، نشان می‌دهد که کدام توابع آن را فراخوانی کرده‌اند و چند بار.
با ماژول
profiling.tracing(یاcProfile)، هر سطر فراخواننده سه عدد را نشان می‌دهد: تعداد فراخوانی‌ها از آن فراخواننده، و زمان‌های کل و تجمعی برای آن فراخوانی‌های خاص.همان آرگومان‌های محدودکننده را مانند
print_stats()می‌پذیرد.
- print_callees(*restrictions)¶
چاپ کردن توابع فراخوانی‌شده توسط هر تابع در آمار.
این کار معکوس
print_callers()است و نشان می‌دهد هر تابع فهرست‌شده چه توابعی را فراخوانی کرده است.همان آرگومان‌های محدودکننده را مانند
print_stats()می‌پذیرد.
- get_stats_profile()¶
یک شیء
StatsProfileحاوی آمار را برمی‌گرداند.شیء برگردانده‌شده دسترسی برنامه‌نویسی به داده‌های پروفایل را فراهم می‌کند، به‌طوری که نام توابع به شیءهای
FunctionProfileحاوی اطلاعات زمان‌بندی و تعداد فراخوانی نگاشت شده‌اند.اضافه شده در نسخه‌ی 3.9.
- class pstats.SortKey¶
شماره‌گذاری کلیدهای مرتب‌سازی معتبر برای
Stats.sort_stats().- CALLS¶
مرتب‌سازی بر اساس تعداد فراخوانی.
- CUMULATIVE¶
مرتب‌سازی بر اساس زمان تجمعی.
- FILENAME¶
مرتب‌سازی بر اساس نام پرونده.
- LINE¶
مرتب‌سازی بر اساس شماره‌ی سطر.
- NAME¶
مرتب‌سازی بر اساس نام تابع.
- NFL¶
مرتب‌سازی بر اساس نام، سپس پرونده و سپس شماره‌ی سطر (مرتب‌سازی عددی سطر).
- PCALLS¶
مرتب‌سازی بر اساس تعداد فراخوانی اولیه (غیربازگشتی).
- STDNAME¶
مرتب‌سازی بر اساس نام استاندارد (مرتب‌سازی سطری مبتنی بر رشته).
- TIME¶
مرتب‌سازی بر اساس زمان داخلی (زمان صرف‌شده در تابع به جز زیرفراخوانی‌ها).
رابط خط فرمان¶
ماژول pstats را می‌توان به عنوان یک اسکریپت برای مرور تعاملی داده‌های پروفایل فراخوانی کرد:
python -m pstats profile_output.prof
این کار یک رابط خط‌مشی‌محور (ساخته‌شده روی cmd) برای بررسی آمار باز می‌کند. برای دستورهای موجود، عبارت help را در اعلان وارد کنید.
همچنین ببینید
profilingنمای کلی ابزارهای پروفایل‌گیری پایتون.
profiling.tracingپروفایل‌گیر ردیابی قطعی.
profiling.samplingپروفایل‌گیر نمونه‌برداری آماری.