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

---

# 26.5. `trace` – Trace or track Python statement execution

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.

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

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

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

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

#### `--help`

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

#### `--version`

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

### 26.5.1.1. Основные параметры

At least one of the following options must be specified when invoking `trace`. The [*--listfuncs*](https://python-all.ru/3.1/library/trace.html#cmdoption-trace-l) option is mutually exclusive with the [*--trace*](https://python-all.ru/3.1/library/trace.html#cmdoption-trace-t) and [*--counts*](https://python-all.ru/3.1/using/cmdline.html#cmdoption-trace-c) options . When [*--listfuncs*](https://python-all.ru/3.1/library/trace.html#cmdoption-trace-l) is provided, neither [*--counts*](https://python-all.ru/3.1/using/cmdline.html#cmdoption-trace-c) nor [*--trace*](https://python-all.ru/3.1/library/trace.html#cmdoption-trace-t) are accepted, and vice versa.

#### `-c, --count`

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

[*--coverdir*](https://python-all.ru/3.1/library/trace.html#cmdoption-trace-C)

,

[*--file*](https://python-all.ru/3.1/library/trace.html#cmdoption-trace-f)

и

[*--no-report*](https://python-all.ru/3.1/using/cmdline.html#cmdoption-trace-R)

ниже.

#### `-t, --trace`

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

#### `-l, --listfuncs`

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

#### `-r, --report`

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

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

и

[*--file*](https://python-all.ru/3.1/library/trace.html#cmdoption-trace-f)

. При этом код не выполняется.

#### `-T, --trackcalls`

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

### 26.5.1.2. Модификаторы

#### `-f, --file=<file>`

Имя файла для накопления счётчиков за несколько сеансов трассировки. Должен использоваться с параметром

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

.

#### `-C, --coverdir=<dir>`

Каталог, в который помещаются файлы отчётов. Отчёт о покрытии для

`package.module`

записывается в файл

`dir/package/module.cover`

.

#### `-m, --missing`

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

`>>>>>>`

.

#### `-s, --summary`

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

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

или

[*--report*](https://python-all.ru/3.1/library/trace.html#cmdoption-trace-r)

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

#### `-R, --no-report`

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

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

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

#### `-g, --timing`

Добавлять к каждой строке время, прошедшее с момента запуска программы. Используется только при трассировке.

### 26.5.1.3. Фильтры

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

#### `--ignore-module=<mod>`

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

#### `--ignore-dir=<dir>`

Игнорировать все модули и пакеты в указанном каталоге и подкаталогах. Аргументом может быть список каталогов, разделённых

[`os.pathsep`](https://python-all.ru/3.1/library/os.html#os.pathsep)

.

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

#### `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.run(cmd)`
>
> Выполняет команду и собирает статистику выполнения с текущими параметрами трассировки.
>
> *cmd*
>
> должна быть строкой или объектом кода, пригодным для передачи в
>
> [`exec()`](https://python-all.ru/3.1/library/functions.html#exec)
>
> .
>
> #### `trace.runctx(cmd, globals=None, locals=None)`
>
> Выполняет команду и собирает статистику выполнения с текущими параметрами трассировки в заданных глобальном и локальном окружениях. Если не заданы,
>
> *globals*
>
> и
>
> *locals*
>
> по умолчанию являются пустыми словарями.
>
> #### `trace.runfunc(func, *args, **kwds)`
>
> Call
>
> *func*
>
> with the given arguments under control of the
>
> `Trace`
>
> object with the current tracing parameters.
>
> #### `trace.results()`
>
> Return a
>
> [`CoverageResults`](https://python-all.ru/3.1/library/trace.html#trace.CoverageResults)
>
> object that contains the cumulative results of all previous calls to
>
> `run`
>
> ,
>
> `runctx`
>
> and
>
> `runfunc`
>
> for the given
>
> `Trace`
>
> instance. Does not reset the accumulated trace results.

#### `class trace.CoverageResults`

A container for coverage results, created by `Trace.results()`. Should not be created directly by the user.

> #### `update(other)`
>
> Объединяет данные из другого объекта
>
> [`CoverageResults`](https://python-all.ru/3.1/library/trace.html#trace.CoverageResults)
>
> .
>
> #### `write_results(show_missing=True, summary=False, coverdir=None)`
>
> Записывает результаты покрытия. Установите
>
> *show\_missing*
>
> , чтобы показывать строки, которые не были выполнены. Установите
>
> *summary*
>
> , чтобы включить в вывод сводку покрытия по модулям.
>
> *coverdir*
>
> задает каталог, в который будут выводиться файлы результатов покрытия. Если
>
> `None`
>
> , результаты для каждого исходного файла помещаются в его каталог.

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

```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")
```