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

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

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

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

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

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

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

--help

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

--version

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

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

При вызове 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=".")