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

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

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

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

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

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

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

--help

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

--version

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

27.6.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

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

27.6.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

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

27.6.1.3. Фильтры

Эти параметры можно повторять несколько раз.

--ignore-module=<mod>

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

--ignore-dir=<dir>

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

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