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 для включения в выходные данные perl-модуля coverage 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=".")
Вернуться на верх