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