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