Содержание страницы

`trace` – трассировка или отслеживание выполнения инструкций Python¶trace – Trace or track Python statement execution

Исходный код: Lib/trace.py

Модуль trace позволяет трассировать выполнение программы, создавать аннотированные списки покрытия инструкций, выводить отношения вызывающий/вызываемый и перечислять функции, выполненные во время запуска программы. Его можно использовать из другой программы или из командной строки.

См. также

Coverage.py: Популярный сторонний инструмент для оценки покрытия, который предоставляет HTML-вывод и расширенные возможности, такие как покрытие ветвлений.

Использование командной строки¶Command-Line Usage

Модуль trace можно вызвать из командной строки. Это может быть так же просто, как

python -m trace --count -C . somefile.py ...

Приведённая выше команда выполнит somefile.py и создаст аннотированные списки всех модулей Python, импортированных во время выполнения, в текущем каталоге.

--help¶: Показать справку и выйти.

--version¶: Отображает версию модуля и завершает работу.

Добавлено в версии 3.8: Добавлена опция --module, которая позволяет запускать исполняемый модуль.

Основные опции¶Main options

При вызове trace необходимо указать хотя бы одну из следующих опций. Опция --listfuncs является взаимоисключающей с опциями --trace и --count. Если указана --listfuncs, то ни --count, ни --trace не принимаются, и наоборот.

-c, --count¶: Создаёт набор аннотированных файлов со списками после завершения программы, показывающих, сколько раз была выполнена каждая инструкция. См. также --coverdir, --file и --no-report ниже.

-t, --trace¶: Отображает строки по мере их выполнения.

-l, --listfuncs¶: Отображает функции, выполненные при запуске программы.

-r, --report¶: Создаёт аннотированный список на основе предыдущего запуска программы, в котором использовались опции --count и --file. При этом код не выполняется.

-T, --trackcalls¶: Отображает отношения вызовов, выявленные при запуске программы.

Модификаторы¶Modifiers

-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¶: Добавлять к каждой строке время, прошедшее с момента запуска программы. Используется только при трассировке.

Фильтры¶Filters

Эти опции можно указывать несколько раз.

--ignore-module=<mod>¶: Игнорировать указанные имена модулей и их подмодули (если это пакет). Аргумент может быть списком имён, разделённых запятыми.

--ignore-dir=<dir>¶: Игнорировать все модули и пакеты в указанном каталоге и подкаталогах. Аргумент может быть списком каталогов, разделённых os.pathsep.

Программный интерфейс¶Programmatic Interface

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

# создать объект 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=".")