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 записывать в 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=".")