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