خواندن و نمایش داده‌های پروفایل¶

کلاس 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)

p = pstats.Stats('restats')
p.strip_dirs().sort_stats(-1).print_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()

p.print_stats(.1)

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)

p.print_callers()

p.print_callees()

# 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 را در اعلان وارد کنید.