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