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