`trace.md`

149 строк · 11.6 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.4/library/trace.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 27.6. [`trace`](https://python-all.ru/3.4/library/trace.html#module-trace) – трассировка или отслеживание выполнения инструкций Python89**Исходный код:** [Lib/trace.py](https://python-all.ru/src/3.4/Lib/trace.py)1011---1213Модуль [`trace`](https://python-all.ru/3.4/library/trace.html#module-trace) позволяет трассировать выполнение программы, создавать аннотированные списки покрытия инструкций, выводить отношения вызывающих и вызываемых функций, а также список функций, выполненных во время запуска программы. Его можно использовать из другой программы или из командной строки.1415## 27.6.1. Использование командной строки1617Модуль [`trace`](https://python-all.ru/3.4/library/trace.html#module-trace) можно вызвать из командной строки. Например, так:1819```python20python -m trace --count -C . somefile.py ...21```2223Приведённая выше команда выполнит `somefile.py` и создаст аннотированные списки всех модулей Python, импортированных во время выполнения, в текущем каталоге.2425#### `--help`2627Показать справку и выйти.2829#### `--version`3031Отображает версию модуля и завершает работу.3233### 27.6.1.1. Основные параметры3435При вызове [`trace`](https://python-all.ru/3.4/library/trace.html#module-trace) должен быть указан как минимум один из следующих параметров. Параметр [*--listfuncs*](https://python-all.ru/3.4/library/trace.html#cmdoption-trace-l) является взаимоисключающим с параметрами [*--trace*](https://python-all.ru/3.4/library/trace.html#cmdoption-trace-t) и [*--count*](https://python-all.ru/3.4/library/trace.html#cmdoption-trace-c). Если указан [*--listfuncs*](https://python-all.ru/3.4/library/trace.html#cmdoption-trace-l), то ни [*--count*](https://python-all.ru/3.4/library/trace.html#cmdoption-trace-c), ни [*--trace*](https://python-all.ru/3.4/library/trace.html#cmdoption-trace-t) не принимаются, и наоборот.3637#### `-c, --count`3839Создаёт набор аннотированных файлов списков после завершения программы, показывающих, сколько раз была выполнена каждая инструкция. См. также [*--coverdir*](https://python-all.ru/3.4/library/trace.html#cmdoption-trace-C), [*--file*](https://python-all.ru/3.4/library/trace.html#cmdoption-trace-f) и [*--no-report*](https://python-all.ru/3.4/library/trace.html#cmdoption-trace-R) ниже.4041#### `-t, --trace`4243Отображает строки по мере их выполнения.4445#### `-l, --listfuncs`4647Отображает функции, выполненные при запуске программы.4849#### `-r, --report`5051Создаёт аннотированный список по результатам предыдущего запуска программы, в котором использовались параметры [*--count*](https://python-all.ru/3.4/library/trace.html#cmdoption-trace-c) и [*--file*](https://python-all.ru/3.4/library/trace.html#cmdoption-trace-f). При этом код не выполняется.5253#### `-T, --trackcalls`5455Отображает отношения вызовов, выявленные при запуске программы.5657### 27.6.1.2. Модификаторы5859#### `-f, --file=<file>`6061Имя файла для накопления счётчиков за несколько сеансов трассировки. Должен использоваться с параметром [*--count*](https://python-all.ru/3.4/library/trace.html#cmdoption-trace-c).6263#### `-C, --coverdir=<dir>`6465Каталог, в который помещаются файлы отчётов. Отчёт о покрытии для `package.module` записывается в файл `dir/package/module.cover`.6667#### `-m, --missing`6869При создании аннотированных списков помечать строки, которые не были выполнены, символом `>>>>>>`.7071#### `-s, --summary`7273При использовании [*--count*](https://python-all.ru/3.4/library/trace.html#cmdoption-trace-c) или [*--report*](https://python-all.ru/3.4/library/trace.html#cmdoption-trace-r) выводит краткую сводку в stdout для каждого обработанного файла.7475#### `-R, --no-report`7677Не создавать аннотированные списки. Это полезно, если планируется выполнить несколько запусков с [*--count*](https://python-all.ru/3.4/library/trace.html#cmdoption-trace-c), а затем создать единый набор аннотированных списков в конце.7879#### `-g, --timing`8081Добавлять к каждой строке время, прошедшее с момента запуска программы. Используется только при трассировке.8283### 27.6.1.3. Фильтры8485Эти опции можно указывать несколько раз.8687#### `--ignore-module=<mod>`8889Игнорировать указанные имена модулей и их подмодули (если это пакет). Аргумент может быть списком имён, разделённых запятыми.9091#### `--ignore-dir=<dir>`9293Игнорировать все модули и пакеты в указанном каталоге и подкаталогах. Аргументом может быть список каталогов, разделённых [`os.pathsep`](https://python-all.ru/3.4/library/os.html#os.pathsep).9495## 27.6.2. Программный интерфейс9697#### `class trace.Trace(count=1, trace=1, countfuncs=0, countcallers=0, ignoremods=(), ignoredirs=(), infile=None, outfile=None, timing=False)`9899Создаёт объект для трассировки выполнения одного оператора или выражения. Все параметры необязательны. *count* включает подсчёт номеров строк. *trace* включает трассировку выполнения строк. *countfuncs* включает вывод списка функций, вызванных во время выполнения. *countcallers* включает отслеживание отношений вызовов. *ignoremods* – это список модулей или пакетов, которые следует игнорировать. *ignoredirs* – это список каталогов, модули или пакеты которых следует игнорировать. *infile* – имя файла, из которого считывается сохранённая информация о подсчётах. *outfile* – имя файла, в который записывается обновлённая информация о подсчётах. *timing* включает отображение временной метки относительно момента начала трассировки.100101> #### `run(cmd)`102>103> Выполняет команду и собирает статистику выполнения с текущими параметрами трассировки. *cmd* должна быть строкой или объектом кода, пригодным для передачи в [`exec()`](https://python-all.ru/3.4/library/functions.html#exec).104>105> #### `runctx(cmd, globals=None, locals=None)`106>107> Выполняет команду и собирает статистику выполнения с текущими параметрами трассировки в заданных глобальном и локальном окружениях. Если не заданы, *globals* и *locals* по умолчанию являются пустыми словарями.108>109> #### `runfunc(func, *args, **kwds)`110>111> Вызывает *func* с заданными аргументами под управлением объекта [`Trace`](https://python-all.ru/3.4/library/trace.html#trace.Trace) с текущими параметрами трассировки.112>113> #### `results()`114>115> Возвращает объект [`CoverageResults`](https://python-all.ru/3.4/library/trace.html#trace.CoverageResults), содержащий накопленные результаты всех предыдущих вызовов `run`, `runctx` и `runfunc` для данного экземпляра [`Trace`](https://python-all.ru/3.4/library/trace.html#trace.Trace). Не сбрасывает накопленные результаты трассировки.116117#### `class trace.CoverageResults`118119Контейнер для результатов покрытия, создаваемый вызовом [`Trace.results()`](https://python-all.ru/3.4/library/trace.html#trace.Trace.results). Не должен создаваться напрямую пользователем.120121> #### `update(other)`122>123> Объединяет данные из другого объекта [`CoverageResults`](https://python-all.ru/3.4/library/trace.html#trace.CoverageResults).124>125> #### `write_results(show_missing=True, summary=False, coverdir=None)`126>127> Записывает результаты покрытия. Установите *show\_missing*, чтобы показывать строки, которые не были выполнены. Установите *summary*, чтобы включить в вывод сводку покрытия по модулям. *coverdir* задает каталог, в который будут выводиться файлы результатов покрытия. Если `None`, результаты для каждого исходного файла помещаются в его каталог.128129Простой пример, демонстрирующий использование программного интерфейса:130131```python132import sys133import trace134135# создать объект Trace, указав, что игнорировать и нужно ли136# выполнять трассировку или подсчёт строк, или и то и другое137tracer = trace.Trace(138    ignoredirs=[sys.prefix, sys.exec_prefix],139    trace=0,140    count=1)141142# запустить новую команду с помощью указанного трассировщика143tracer.run('main()')144145# сформировать отчёт, помещая вывод в текущий каталог146r = tracer.results()147r.write_results(show_missing=True, coverdir=".")148```149