отслеживание — Отслеживание или прослеживание выполнения утверждений 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, чтобы включить в вывод сводку покрытия по модулям. 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=".")