> **Источник:** https://python-all.ru/3.0/library/trace.html
>
> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.

---

# `trace` – трассировка или отслеживание выполнения операторов Python

The `trace` module allows you to trace program execution, generate annotated statement coverage listings, print caller/callee relationships and list functions executed during a program run. It can be used in another program or from the command line.

## Использование командной строки

The `trace` module can be invoked from the command line. It can be as simple as

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

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

Поддерживаются следующие аргументы командной строки:

***--trace*, *-t***

Отображает строки по мере их выполнения.

***--count*, [*-c*](https://python-all.ru/3.0/using/cmdline.html#cmdoption-c)**

Создаёт набор аннотированных файлов листингов по завершении программы, показывающих, сколько раз выполнялся каждый оператор.

***--report*, *-r***

Создаёт аннотированный список на основе предыдущего запуска программы, в котором использовались аргументы

*--count*

и

*--file*

.

***--no-report*, *-R***

Не создавать аннотированные листинги. Это полезно, если планируется выполнить несколько запусков с

*--count*

, а затем сформировать единый набор аннотированных листингов в конце.

***--listfuncs*, *-l***

Выводит список функций, выполненных в ходе работы программы.

***--trackcalls*, *-T***

Формирует информацию о вызовах, обнаруженных при выполнении программы.

***--file*, *-f***

Указывает файл, содержащий (или предназначенный для хранения) счётчиков.

***--coverdir*, *-C***

Указывает каталог для сохранения аннотированных файлов листингов.

***--missing*, [*-m*](https://python-all.ru/3.0/using/cmdline.html#cmdoption-m)**

При создании аннотированных листингов помечать строки, которые не выполнялись, символом ‘

`>>>>>>`

‘.

***--summary*, [*-s*](https://python-all.ru/3.0/using/cmdline.html#cmdoption-s)**

При использовании

*--count*

или

*--report*

выводить краткую сводку в stdout для каждого обработанного файла.

***--ignore-module***

Принимает разделённый запятыми список имён модулей. Игнорирует каждый указанный модуль и его подмодули (если это пакет). Можно указывать несколько раз.

***--ignore-dir***

Игнорирует все модули и пакеты в указанном каталоге и подкаталогах (несколько каталогов можно объединить через os.pathsep). Можно указывать несколько раз.

## Программный интерфейс

#### `[trace.Trace]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*

включает отображение временной метки относительно момента начала трассировки.

#### `[trace.Trace.run]Trace.run(cmd)`

Запускает

*cmd*

под управлением объекта Trace с текущими параметрами трассировки.

#### `[trace.Trace.runctx]Trace.runctx(cmd[, globals=None[, locals=None]])`

Запускает

*cmd*

под управлением объекта Trace с текущими параметрами трассировки в заданных глобальном и локальном окружениях. Если они не заданы,

*globals*

и

*locals*

по умолчанию равны пустым словарям.

#### `[trace.Trace.runfunc]Trace.runfunc(func, *args, **kwds)`

Вызывает

*func*

с заданными аргументами под управлением объекта

[`Trace`](https://python-all.ru/3.0/library/trace.html#trace.Trace)

с текущими параметрами трассировки.

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

```python
import sys
import trace

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

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

# создать отчёт, поместив вывод в /tmp
r = tracer.results()
r.write_results(show_missing=True, coverdir="/tmp")
```