trace
— Трассировка или отслеживание выполнения операторов Python¶
Источник: Lib/trace.py
Модуль trace
позволяет отслеживать выполнение программы, генерировать аннотированные листинги покрытия операторов, выводить отношения caller/callee и список функций, выполняемых во время выполнения программы. Его можно использовать в другой программе или из командной строки.
См.также
- Coverage.py
Популярный инструмент покрытия от сторонних разработчиков, предоставляющий HTML-вывод, а также расширенные возможности, такие как покрытие ветвей.
Использование командной строки¶
Модуль trace
можно вызвать из командной строки. Это может быть просто
python -m trace --count -C . somefile.py ...
Вышеописанное выполнит somefile.py
и сгенерирует аннотированные списки всех модулей Python, импортированных во время выполнения в текущий каталог.
- --help¶
Отображение использования и выход.
- --version¶
Вывести версию модуля и выйти.
Added in 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, *, 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=".")