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

Исходный код: Lib/trace.py

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

См. также

Coverage.py: Популярный сторонний инструмент покрытия кода, предоставляющий HTML-вывод вместе с расширенными функциями, такими как покрытие ветвей.

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

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

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

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

--help: Отобразить справку и выйти.

--version: Отобразить версию модуля и выйти.

New 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, выводить краткое резюме в стандартный вывод для каждого обработанного файла.

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