trace — Трассировка или отслеживание выполнения инструкции Python


Модуль 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 для каждого обработанного файла напишите краткое резюме stdout.

-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

# создать объект Trace, указав, что следует игнорировать и выполнять трассировку
# или подсчет строк или и то, и другое.
tracer = trace.Trace(
    ignoredirs=[sys.prefix, sys.exec_prefix],
    trace=0,
    count=1)

# запустить новую команду, используя данный трассировщик
tracer.run('main()')

# составить отчет, разместив вывод в текущем каталоге
r = tracer.results()
r.write_results(show_missing=True, coverdir=".")