trace — Отслеживание выполнения инструкций Python

Исходный код: Lib/trace.py

Модуль trace позволяет отслеживать выполнение программы, генерировать аннотированные списки покрытия инструкций, отображать отношения вызывающих/вызываемых функций и список исполненных функций во время выполнения программы. Он может быть использован в другой программе или из командной строки.

См. также

Coverage.py: Популярный инструмент для анализа покрытия кода сторонних разработчиков, который предоставляет HTML-вывод вместе с расширенными функциями, такими как анализ покрытия ветвлений.

Использование в командной строке

Модуль trace может быть вызван из командной строки. Это может быть так просто, как

python -m trace --count -C . somefile.py ...

Вышеуказанное выполнит somefile.py и сгенерирует аннотированные списки всех импортированных модулей Python во время выполнения в текущем каталоге.

--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, выводить краткий сводный отчет в стандартный вывод для каждого обработанного файла.

-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): Записать результаты покрытия. Установить show_missing для отображения строк без попаданий. Установить summary для включения в вывод сводного отчета по модулям. coverdir указывает каталог, в который будут выведены файлы результатов покрытия. Если None, результаты для каждого исходного файла размещаются в соответствующем каталоге.

Простой пример использования программного интерфейса:

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=".")