`pstats.md`

308 строк · 18.0 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.16/library/pstats.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `pstats` – Статистика для профилировщиков89**Исходный код:** [Lib/pstats.py](https://python-all.ru/src/main/Lib/pstats.py)1011---1213Модуль `pstats` предоставляет инструменты для чтения, обработки и отображения статистики профилирования, созданной профилировщиками Python. Он читает выходные данные как от [`profiling.tracing`](https://python-all.ru/3.16/library/profiling.tracing.html#module-profiling.tracing) (детерминированного профилировщика), так и от [`profiling.sampling`](https://python-all.ru/3.16/library/profiling.sampling.html#module-profiling.sampling) (статистического профилировщика).1415## Чтение и отображение данных профиля1617Класс [`Stats`](https://python-all.ru/3.16/library/pstats.html#pstats.Stats) является основным интерфейсом для работы с данными профиля. Он может читать статистику из файлов или напрямую из объекта [`Profile`](https://python-all.ru/3.16/library/profiling.tracing.html#profiling.tracing.Profile).1819Загрузка статистики из файла и вывод базового отчета:2021```python22import pstats2324p = pstats.Stats('profile_output.prof')25p.print_stats()26```2728Объект [`Stats`](https://python-all.ru/3.16/library/pstats.html#pstats.Stats) предоставляет методы для сортировки и фильтрации данных перед выводом. Например, чтобы увидеть десять функций с наибольшим кумулятивным временем:2930```python31from pstats import SortKey3233p = pstats.Stats('profile_output.prof')34p.sort_stats(SortKey.CUMULATIVE).print_stats(10)35```3637### Работа со статистикой3839Класс [`Stats`](https://python-all.ru/3.16/library/pstats.html#pstats.Stats) поддерживает цепочки методов, что позволяет удобно выполнять несколько операций:4041```python42p = pstats.Stats('restats')43p.strip_dirs().sort_stats(-1).print_stats()44```4546Метод [`strip_dirs()`](https://python-all.ru/3.16/library/pstats.html#pstats.Stats.strip_dirs) удаляет пути к каталогам из имён файлов, делая вывод более компактным. Метод [`sort_stats()`](https://python-all.ru/3.16/library/pstats.html#pstats.Stats.sort_stats) принимает различные ключи для управления порядком сортировки.4748Различные ключи сортировки выделяют разные аспекты производительности:4950```python51from pstats import SortKey5253# Функции, потребляющие больше всего совокупного времени54p.sort_stats(SortKey.CUMULATIVE).print_stats(10)5556# Функции, потребляющие больше всего времени в собственном коде57p.sort_stats(SortKey.TIME).print_stats(10)5859# Функции, отсортированные по имени60p.sort_stats(SortKey.NAME).print_stats()61```6263### Фильтрация вывода6465Метод [`print_stats()`](https://python-all.ru/3.16/library/pstats.html#pstats.Stats.print_stats) принимает ограничения, которые фильтруют отображаемые функции. Ограничения могут быть целыми числами (ограничение количества), числами с плавающей точкой от 0 до 1 (выбор процента) или строками (сопоставление имён функций с помощью регулярного выражения).6667Вывести только верхние 10%:6869```python70p.print_stats(.1)71```7273Вывести только функции, имена которых содержат «init»:7475```python76p.print_stats('init')77```7879Комбинирование ограничений (они применяются последовательно):8081```python82# Лучшие 10%, затем только те, что содержат "init"83p.print_stats(.1, 'init')8485# Функции из файлов, соответствующих "foo:", с ограничением до верхних 50%86p.sort_stats(SortKey.FILENAME).print_stats('foo:', .5)87```8889### Анализ отношений вызовов9091Метод [`print_callers()`](https://python-all.ru/3.16/library/pstats.html#pstats.Stats.print_callers) показывает, какие функции вызывали каждую отображаемую функцию:9293```python94p.print_callers()95```9697Метод [`print_callees()`](https://python-all.ru/3.16/library/pstats.html#pstats.Stats.print_callees) показывает обратное отношение, перечисляя, какие функции вызывала каждая отображаемая функция:9899```python100p.print_callees()101```102103Оба метода принимают те же аргументы ограничения, что и [`print_stats()`](https://python-all.ru/3.16/library/pstats.html#pstats.Stats.print_stats).104105### Объединение нескольких профилей106107Статистику из нескольких сеансов профилирования можно объединить в один объект [`Stats`](https://python-all.ru/3.16/library/pstats.html#pstats.Stats):108109```python110# Загрузить несколько файлов за один раз111p = pstats.Stats('run1.prof', 'run2.prof', 'run3.prof')112113# Или добавлять файлы постепенно114p = pstats.Stats('run1.prof')115p.add('run2.prof')116p.add('run3.prof')117```118119При объединении файлов статистика для одинаковых функций (одинаковый файл, строка и имя) накапливается, давая обобщённое представление по всем сеансам профилирования.120121## Класс `Stats`122123#### `class pstats.Stats(*filenames_or_profile, stream=sys.stdout)`124125Создание объекта статистики из данных профиля.126127Аргументами могут быть имена файлов (строки или объекты, подобные пути) или объекты [`Profile`](https://python-all.ru/3.16/library/profiling.tracing.html#profiling.tracing.Profile). Если указано несколько источников, их статистика объединяется.128129Аргумент *поток данных* указывает, куда записывается вывод [`print_stats()`](https://python-all.ru/3.16/library/pstats.html#pstats.Stats.print_stats) и связанных методов. По умолчанию он равен [`sys.stdout`](https://python-all.ru/3.16/library/sys.html#sys.stdout).130131Формат данных профиля зависит от версии Python, в которой он был создан. Нет гарантии совместимости между версиями Python или между разными профилировщиками.132133#### `strip_dirs()`134135Удалить информацию о пути из всех имён файлов.136137Этот метод изменяет объект на месте и возвращает его для цепочки методов. После удаления путей считается, что статистика находится в случайном порядке.138139Если обрезание приводит к тому, что две функции становятся неразличимыми (одинаковые имя файла, номер строки и имя функции), их статистика объединяется в одну запись.140141#### `add(*filenames)`142143Добавляет данные профилирования из дополнительных файлов.144145Файлы должны быть созданы одним и тем же типом профилировщика. Статистика для одинаковых функций накапливается.146147#### `dump_stats(filename)`148149Сохраняет текущую статистику в файл.150151Файл создаётся, если его не существует, и перезаписывается, если он существует. Сохранённые данные можно загрузить, создав новый объект `Stats`.152153#### `sort_stats(*keys)`154155Сортирует статистику по заданным критериям.156157Каждый ключ может быть строкой или элементом перечисления [`SortKey`](https://python-all.ru/3.16/library/pstats.html#pstats.SortKey). Если указано несколько ключей, последующие ключи разрешают равенства предыдущих.158159Использование элементов перечисления [`SortKey`](https://python-all.ru/3.16/library/pstats.html#pstats.SortKey) предпочтительнее строк, так как это обеспечивает лучшую проверку ошибок:160161```python162from pstats import SortKey163p.sort_stats(SortKey.CUMULATIVE)164```165166Допустимые ключи сортировки:167168| Строка | Перечисление | Значение |169| --- | --- | --- |170| `'calls'` | `SortKey.CALLS` | количество вызовов |171| `'cumulative'` | `SortKey.CUMULATIVE` | совокупное время |172| `'cumtime'` | Н/Д | совокупное время |173| `'file'` | Н/Д | имя файла |174| `'filename'` | `SortKey.FILENAME` | имя файла |175| `'module'` | Н/Д | имя файла |176| `'ncalls'` | Н/Д | количество вызовов |177| `'pcalls'` | `SortKey.PCALLS` | количество примитивных вызовов |178| `'line'` | `SortKey.LINE` | номер строки |179| `'name'` | `SortKey.NAME` | имя функции |180| `'nfl'` | `SortKey.NFL` | имя/файл/строка |181| `'stdname'` | `SortKey.STDNAME` | стандартное имя |182| `'time'` | `SortKey.TIME` | внутреннее время |183| `'tottime'` | Н/Д | внутреннее время |184185Все сортировки статистики выполняются по убыванию (самые затратные по времени первые), в то время как сортировки по имени, файлу и номеру строки выполняются по возрастанию (в алфавитном порядке).186187Разница между `SortKey.NFL` и `SortKey.STDNAME` в том, что NFL сортирует номера строк численно, а STDNAME – как строки. `sort_stats(SortKey.NFL)` эквивалентно `sort_stats(SortKey.NAME, SortKey.FILENAME, SortKey.LINE)`.188189Для обратной совместимости также принимаются числовые аргументы `-1`, `0`, `1`, и `2`, означающие соответственно `'stdname'`, `'calls'`, `'time'` и `'cumulative'`.190191Добавлено в версии 3.7: Перечисление [`SortKey`](https://python-all.ru/3.16/library/pstats.html#pstats.SortKey).192193#### `reverse_order()`194195Меняет текущий порядок сортировки на обратный.196197По умолчанию направление сортировки выбирается подходящим для ключа сортировки (по убыванию для ключей на основе времени, по возрастанию для ключей на основе имени). Этот метод инвертирует этот выбор.198199#### `print_stats(*restrictions)`200201Выводит отчёт о статистике профилирования.202203Вывод включает строку заголовка, суммирующую данные, за которой следует таблица статистики функций, отсортированная согласно последнему вызову [`sort_stats()`](https://python-all.ru/3.16/library/pstats.html#pstats.Stats.sort_stats).204205Ограничения фильтруют вывод. Каждое ограничение является либо:206207- Целое число: ограничивает вывод указанным количеством записей208- Число с плавающей точкой от 0.0 до 1.0: выбирает указанную долю записей209- Строка: сопоставляет имена функций с помощью регулярного выражения210211Ограничения применяются последовательно. Например:212213```python214print_stats(.1, 'foo:')215```216217Сначала ограничивает до верхних 10%, затем фильтрует по функциям, соответствующим 'foo:'.218219#### `print_callers(*restrictions)`220221Выводит вызывающие функции для каждой функции в статистике.222223Для каждой функции в отфильтрованных результатах показывает, какие функции вызывали её и как часто.224225С помощью [`profiling.tracing`](https://python-all.ru/3.16/library/profiling.tracing.html#module-profiling.tracing) (или `cProfile`) каждая строка вызывающей функции показывает три числа: количество вызовов от этого вызывающего, а также общее и накопленное время для этих вызовов.226227Принимает те же аргументы ограничений, что и [`print_stats()`](https://python-all.ru/3.16/library/pstats.html#pstats.Stats.print_stats).228229#### `print_callees(*restrictions)`230231Печатает функции, вызываемые каждой функцией в статистике.232233Это обратная операция к [`print_callers()`](https://python-all.ru/3.16/library/pstats.html#pstats.Stats.print_callers): показывает, какие функции вызывала каждая из перечисленных функций.234235Принимает те же аргументы ограничений, что и [`print_stats()`](https://python-all.ru/3.16/library/pstats.html#pstats.Stats.print_stats).236237#### `get_stats_profile()`238239Возвращает объект `StatsProfile`, содержащий статистику.240241Возвращаемый объект предоставляет программный доступ к данным профилирования: имена функций сопоставляются с объектами `FunctionProfile`, содержащими информацию о времени и количестве вызовов.242243Добавлено в версии 3.9.244245#### `class pstats.SortKey`246247Перечисление допустимых ключей сортировки для [`Stats.sort_stats()`](https://python-all.ru/3.16/library/pstats.html#pstats.Stats.sort_stats).248249#### `CALLS`250251Сортировать по количеству вызовов.252253#### `CUMULATIVE`254255Сортировать по накопленному времени.256257#### `FILENAME`258259Сортировать по имени файла.260261#### `LINE`262263Сортировать по номеру строки.264265#### `NAME`266267Сортировать по имени функции.268269#### `NFL`270271Сортировать по имени, затем по файлу, затем по номеру строки (числовая сортировка строк).272273#### `PCALLS`274275Сортировать по количеству примитивных (нерекурсивных) вызовов.276277#### `STDNAME`278279Сортировать по стандартному имени (строковая сортировка строк).280281#### `TIME`282283Сортировать по внутреннему времени (время внутри функции без учёта вызовов).284285## Интерфейс командной строки286287Модуль `pstats` можно запустить как скрипт для интерактивного просмотра данных профилирования:288289```python290python -m pstats profile_output.prof291```292293Откроется интерфейс, ориентированный на строки (построенный на [`cmd`](https://python-all.ru/3.16/library/cmd.html#module-cmd)), для просмотра статистики. Введите `help` в приглашении, чтобы увидеть доступные команды.294295> **См. также**296>297> **[`profiling`](https://python-all.ru/3.16/library/profiling.html#module-profiling)**298>299> Обзор инструментов профилирования Python.300>301> **[`profiling.tracing`](https://python-all.ru/3.16/library/profiling.tracing.html#module-profiling.tracing)**302>303> Детерминированный трассирующий профилировщик.304>305> **[`profiling.sampling`](https://python-all.ru/3.16/library/profiling.sampling.html#module-profiling.sampling)**306>307> Статистический профилировщик на основе выборки.308