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

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

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

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

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

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

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

--help

Показать использование и завершить.

--version

Показать версию модуля и завершить.

1.1. Основные параметры

При вызове trace должен быть указан хотя бы один из следующих параметров. Параметр --listfuncs взаимоисключающий с параметрами --trace и --count. Когда указан параметр --listfuncs, ни --count, ни --trace не принимаются, и наоборот.

-c, --count

Создает набор аннотированных файлов списков по завершении программы, показывающий, сколько раз выполнялся каждый оператор. См. также --coverdir, --file и --no-report ниже.

-t, --trace

Отображать строки по мере их выполнения.

-l, --listfuncs

Отобразить функции, выполняемые при запуске программы.

-r, --report

Создает аннотированный список из предыдущего выполнения программы, использующего параметр --count и --file. Это не выполняет код.

-T, --trackcalls

Отобразить отношения вызовов, созданные при запуске программы.

1.2. Модификаторы

-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

Префикс каждой строки с временем, прошедшим с момента запуска программы. Используется только при отслеживании.

1.3. Фильтры

Эти параметры могут быть повторены несколько раз.

--ignore-module=<mod>

Игнорировать каждое из указанных имён модулей и его подмодули (если это пакет). Аргумент может быть списком имён, разделённых запятой.

--ignore-dir=<dir>

Игнорировать все модули и пакеты в указанном каталоге и его подкаталогах. Аргумент может быть списком каталогов, разделённых os.pathsep.

2. Программный интерфейс

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