отслеживание — Отслеживание или прослеживание выполнения операторов 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, *, ignore_missing_files=False)

Записывает результаты покрытия. Установите show_missing, чтобы отобразить строки без попаданий. Установите summary, чтобы включить в вывод сводку покрытия по модулям. coverdir указывает каталог, в который будут выведены файлы результатов покрытия. Если None, результаты для каждого исходного файла размещаются в соответствующем каталоге.

Если ignore_missing_files True, счётчики покрытия для файлов, которые больше не существуют, будут проигнорированы. В противном случае, отсутствующий файл вызовет исключение FileNotFoundError.

Изменено в версии 3.13: Добавлен параметр ignore_missing_files.

Простой пример, демонстрирующий использование программного интерфейса:

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