trace — Трассировка или отслеживание выполнения операторов Python

Источник: Lib/trace.py

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

См.также

Coverage.py

Популярный инструмент покрытия от сторонних разработчиков, предоставляющий HTML-вывод, а также расширенные возможности, такие как покрытие ветвей.

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

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

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

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

--help

Отображение использования и выход.

--version

Вывести версию модуля и выйти.

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