`trace.md`

157 строк · 12.0 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.9/library/trace.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# [`trace`](https://python-all.ru/3.9/library/trace.html#module-trace) – трассировка или отслеживание выполнения инструкций Python89**Исходный код:** [Lib/trace.py](https://python-all.ru/src/3.9/Lib/trace.py)1011---1213Модуль [`trace`](https://python-all.ru/3.9/library/trace.html#module-trace) позволяет трассировать выполнение программы, создавать аннотированные списки покрытия инструкций, выводить отношения вызывающий/вызываемый и перечислять функции, выполненные во время запуска программы. Его можно использовать из другой программы или из командной строки.1415> **См. также**16>17> **[Coverage.py](https://python-all.ru/3.9/library/trace.html)**18>19> Популярный сторонний инструмент для оценки покрытия, который предоставляет HTML-вывод и расширенные возможности, такие как покрытие ветвлений.2021## Использование командной строки2223Модуль [`trace`](https://python-all.ru/3.9/library/trace.html#module-trace) можно вызвать из командной строки. Это может быть так же просто, как2425```python26python -m trace --count -C . somefile.py ...27```2829Приведённая выше команда выполнит `somefile.py` и создаст аннотированные списки всех модулей Python, импортированных во время выполнения, в текущем каталоге.3031#### `--help`3233Показать справку и выйти.3435#### `--version`3637Отображает версию модуля и завершает работу.3839Новое в версии 3.8: Добавлена `--module` опция, позволяющая запускать исполняемый модуль.4041### Основные опции4243При вызове [`trace`](https://python-all.ru/3.9/library/trace.html#module-trace) необходимо указать хотя бы одну из следующих опций. Опция [`--listfuncs`](https://python-all.ru/3.9/library/trace.html#cmdoption-trace-l) является взаимоисключающей с опциями [`--trace`](https://python-all.ru/3.9/library/trace.html#cmdoption-trace-t) и [`--count`](https://python-all.ru/3.9/library/trace.html#cmdoption-trace-c). Если указана [`--listfuncs`](https://python-all.ru/3.9/library/trace.html#cmdoption-trace-l), то ни [`--count`](https://python-all.ru/3.9/library/trace.html#cmdoption-trace-c), ни [`--trace`](https://python-all.ru/3.9/library/trace.html#cmdoption-trace-t) не принимаются, и наоборот.4445#### `-c, --count`4647Создаёт набор аннотированных файлов со списками после завершения программы, показывающих, сколько раз была выполнена каждая инструкция. См. также [`--coverdir`](https://python-all.ru/3.9/library/trace.html#cmdoption-trace-coverdir), [`--file`](https://python-all.ru/3.9/library/trace.html#cmdoption-trace-f) и [`--no-report`](https://python-all.ru/3.9/library/trace.html#cmdoption-trace-no-report) ниже.4849#### `-t, --trace`5051Отображает строки по мере их выполнения.5253#### `-l, --listfuncs`5455Отображает функции, выполненные при запуске программы.5657#### `-r, --report`5859Создаёт аннотированный список на основе предыдущего запуска программы, в котором использовались опции [`--count`](https://python-all.ru/3.9/library/trace.html#cmdoption-trace-c) и [`--file`](https://python-all.ru/3.9/library/trace.html#cmdoption-trace-f). При этом код не выполняется.6061#### `-T, --trackcalls`6263Отображает отношения вызовов, выявленные при запуске программы.6465### Модификаторы6667#### `-f, --file=<file>`6869Имя файла для накопления счётчиков в течение нескольких трассировок. Должна использоваться с опцией [`--count`](https://python-all.ru/3.9/library/trace.html#cmdoption-trace-c).7071#### `-C, --coverdir=<dir>`7273Каталог, в который помещаются файлы отчётов. Отчёт о покрытии для `package.module` записывается в файл `dir/package/module.cover`.7475#### `-m, --missing`7677При создании аннотированных списков помечать строки, которые не были выполнены, символом `>>>>>>`.7879#### `-s, --summary`8081При использовании [`--count`](https://python-all.ru/3.9/library/trace.html#cmdoption-trace-c) или [`--report`](https://python-all.ru/3.9/library/trace.html#cmdoption-trace-r) выводите краткую сводку в stdout для каждого обработанного файла.8283#### `-R, --no-report`8485Не создавать аннотированные листинги. Это полезно, если планируется выполнить несколько запусков с [`--count`](https://python-all.ru/3.9/library/trace.html#cmdoption-trace-c), а затем в конце сформировать единый набор аннотированных листингов.8687#### `-g, --timing`8889Добавлять к каждой строке время, прошедшее с момента запуска программы. Используется только при трассировке.9091### Фильтры9293Эти опции можно указывать несколько раз.9495#### `--ignore-module=<mod>`9697Игнорировать указанные имена модулей и их подмодули (если это пакет). Аргумент может быть списком имён, разделённых запятыми.9899#### `--ignore-dir=<dir>`100101Игнорировать все модули и пакеты в указанном каталоге и подкаталогах. Аргумент может быть списком каталогов, разделённых [`os.pathsep`](https://python-all.ru/3.9/library/os.html#os.pathsep).102103## Программный интерфейс104105#### `class trace.Trace(count=1, trace=1, countfuncs=0, countcallers=0, ignoremods=(), ignoredirs=(), infile=None, outfile=None, timing=False)`106107Создаёт объект для трассировки выполнения одного оператора или выражения. Все параметры необязательны. *count* включает подсчёт номеров строк. *trace* включает трассировку выполнения строк. *countfuncs* включает вывод списка функций, вызванных во время выполнения. *countcallers* включает отслеживание отношений вызовов. *ignoremods* – это список модулей или пакетов, которые следует игнорировать. *ignoredirs* – это список каталогов, модули или пакеты которых следует игнорировать. *infile* – имя файла, из которого считывается сохранённая информация о подсчётах. *outfile* – имя файла, в который записывается обновлённая информация о подсчётах. *timing* включает отображение временной метки относительно момента начала трассировки.108109#### `run(cmd)`110111Выполняет команду и собирает статистику выполнения с текущими параметрами трассировки. *cmd* должен быть строкой или объектом кода, пригодным для передачи в [`exec()`](https://python-all.ru/3.9/library/functions.html#exec).112113#### `runctx(cmd, globals=None, locals=None)`114115Выполняет команду и собирает статистику выполнения с текущими параметрами трассировки в заданных глобальном и локальном окружениях. Если не заданы, *globals* и *locals* по умолчанию являются пустыми словарями.116117#### `runfunc(func, /, *args, **kwds)`118119Вызывает *func* с заданными аргументами под управлением объекта [`Trace`](https://python-all.ru/3.9/library/trace.html#trace.Trace) с текущими параметрами трассировки.120121#### `results()`122123Возвращает объект [`CoverageResults`](https://python-all.ru/3.9/library/trace.html#trace.CoverageResults), содержащий накопленные результаты всех предыдущих вызовов `run`, `runctx` и `runfunc` для данного экземпляра [`Trace`](https://python-all.ru/3.9/library/trace.html#trace.Trace). Не сбрасывает накопленные результаты трассировки.124125#### `class trace.CoverageResults`126127Контейнер для результатов покрытия, создаваемый [`Trace.results()`](https://python-all.ru/3.9/library/trace.html#trace.Trace.results). Не должен создаваться непосредственно пользователем.128129#### `update(other)`130131Объединяет данные из другого объекта [`CoverageResults`](https://python-all.ru/3.9/library/trace.html#trace.CoverageResults).132133#### `write_results(show_missing=True, summary=False, coverdir=None)`134135Записывает результаты покрытия. Установите *show\_missing*, чтобы отображать строки, которые не были выполнены. Установите *summary*, чтобы включить в вывод сводку покрытия для каждого модуля. *coverdir* задаёт каталог, в который будут выведены файлы результатов покрытия. Если `None`, результаты для каждого исходного файла помещаются в его собственный каталог.136137Простой пример, демонстрирующий использование программного интерфейса:138139```python140import sys141import trace142143# создать объект Trace, указав, что игнорировать и нужно ли144# выполнять трассировку или подсчёт строк, или и то и другое145tracer = trace.Trace(146    ignoredirs=[sys.prefix, sys.exec_prefix],147    trace=0,148    count=1)149150# запустить новую команду с помощью указанного трассировщика151tracer.run('main()')152153# сформировать отчёт, помещая вывод в текущий каталог154r = tracer.results()155r.write_results(show_missing=True, coverdir=".")156```157