`trace.md`

263 строк · 10.4 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.1/library/trace.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 26.5. `trace` – Trace or track Python statement execution89The `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.1011## 26.5.1. Использование командной строки1213The `trace` module can be invoked from the command line. It can be as simple as1415```python16python -m trace --count -C . somefile.py ...17```1819Приведённая выше команда выполнит `somefile.py` и создаст аннотированные списки всех модулей Python, импортированных во время выполнения, в текущем каталоге.2021#### `--help`2223Показать справку и выйти.2425#### `--version`2627Отображает версию модуля и завершает работу.2829### 26.5.1.1. Основные параметры3031At 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.3233#### `-c, --count`3435Создаёт набор аннотированных файлов списков после завершения программы, показывающих, сколько раз была выполнена каждая инструкция. См. также3637[*--coverdir*](https://python-all.ru/3.1/library/trace.html#cmdoption-trace-C)3839,4041[*--file*](https://python-all.ru/3.1/library/trace.html#cmdoption-trace-f)4243и4445[*--no-report*](https://python-all.ru/3.1/using/cmdline.html#cmdoption-trace-R)4647ниже.4849#### `-t, --trace`5051Отображает строки по мере их выполнения.5253#### `-l, --listfuncs`5455Отображает функции, выполненные при запуске программы.5657#### `-r, --report`5859Создаёт аннотированный список по результатам предыдущего запуска программы, в котором использовались параметры6061[*--count*](https://python-all.ru/3.1/using/cmdline.html#cmdoption-trace-c)6263и6465[*--file*](https://python-all.ru/3.1/library/trace.html#cmdoption-trace-f)6667. При этом код не выполняется.6869#### `-T, --trackcalls`7071Отображает отношения вызовов, выявленные при запуске программы.7273### 26.5.1.2. Модификаторы7475#### `-f, --file=<file>`7677Имя файла для накопления счётчиков за несколько сеансов трассировки. Должен использоваться с параметром7879[*--count*](https://python-all.ru/3.1/using/cmdline.html#cmdoption-trace-c)8081.8283#### `-C, --coverdir=<dir>`8485Каталог, в который помещаются файлы отчётов. Отчёт о покрытии для8687`package.module`8889записывается в файл9091`dir/package/module.cover`9293.9495#### `-m, --missing`9697При создании аннотированных списков помечать строки, которые не были выполнены, символом9899`>>>>>>`100101.102103#### `-s, --summary`104105При использовании106107[*--count*](https://python-all.ru/3.1/using/cmdline.html#cmdoption-trace-c)108109или110111[*--report*](https://python-all.ru/3.1/library/trace.html#cmdoption-trace-r)112113выводит краткую сводку в stdout для каждого обработанного файла.114115#### `-R, --no-report`116117Не создавать аннотированные списки. Это полезно, если планируется выполнить несколько запусков с118119[*--count*](https://python-all.ru/3.1/using/cmdline.html#cmdoption-trace-c)120121, а затем создать единый набор аннотированных списков в конце.122123#### `-g, --timing`124125Добавлять к каждой строке время, прошедшее с момента запуска программы. Используется только при трассировке.126127### 26.5.1.3. Фильтры128129Эти опции можно указывать несколько раз.130131#### `--ignore-module=<mod>`132133Игнорировать указанные имена модулей и их подмодули (если это пакет). Аргумент может быть списком имён, разделённых запятыми.134135#### `--ignore-dir=<dir>`136137Игнорировать все модули и пакеты в указанном каталоге и подкаталогах. Аргументом может быть список каталогов, разделённых138139[`os.pathsep`](https://python-all.ru/3.1/library/os.html#os.pathsep)140141.142143## 26.5.2. Программный интерфейс144145#### `Trace(count=1, trace=1, countfuncs=0, countcallers=0, ignoremods=(),\`146147#### `ignoredirs=(), infile=None, outfile=None, timing=False)`148149Создаёт объект для трассировки выполнения одного оператора или выражения. Все параметры необязательны. *count* включает подсчёт номеров строк. *trace* включает трассировку выполнения строк. *countfuncs* включает вывод списка функций, вызванных во время выполнения. *countcallers* включает отслеживание отношений вызовов. *ignoremods* – это список модулей или пакетов, которые следует игнорировать. *ignoredirs* – это список каталогов, модули или пакеты которых следует игнорировать. *infile* – имя файла, из которого считывается сохранённая информация о подсчётах. *outfile* – имя файла, в который записывается обновлённая информация о подсчётах. *timing* включает отображение временной метки относительно момента начала трассировки.150151> #### `trace.run(cmd)`152>153> Выполняет команду и собирает статистику выполнения с текущими параметрами трассировки.154>155> *cmd*156>157> должна быть строкой или объектом кода, пригодным для передачи в158>159> [`exec()`](https://python-all.ru/3.1/library/functions.html#exec)160>161> .162>163> #### `trace.runctx(cmd, globals=None, locals=None)`164>165> Выполняет команду и собирает статистику выполнения с текущими параметрами трассировки в заданных глобальном и локальном окружениях. Если не заданы,166>167> *globals*168>169> и170>171> *locals*172>173> по умолчанию являются пустыми словарями.174>175> #### `trace.runfunc(func, *args, **kwds)`176>177> Call178>179> *func*180>181> with the given arguments under control of the182>183> `Trace`184>185> object with the current tracing parameters.186>187> #### `trace.results()`188>189> Return a190>191> [`CoverageResults`](https://python-all.ru/3.1/library/trace.html#trace.CoverageResults)192>193> object that contains the cumulative results of all previous calls to194>195> `run`196>197> ,198>199> `runctx`200>201> and202>203> `runfunc`204>205> for the given206>207> `Trace`208>209> instance. Does not reset the accumulated trace results.210211#### `class trace.CoverageResults`212213A container for coverage results, created by `Trace.results()`. Should not be created directly by the user.214215> #### `update(other)`216>217> Объединяет данные из другого объекта218>219> [`CoverageResults`](https://python-all.ru/3.1/library/trace.html#trace.CoverageResults)220>221> .222>223> #### `write_results(show_missing=True, summary=False, coverdir=None)`224>225> Записывает результаты покрытия. Установите226>227> *show\_missing*228>229> , чтобы показывать строки, которые не были выполнены. Установите230>231> *summary*232>233> , чтобы включить в вывод сводку покрытия по модулям.234>235> *coverdir*236>237> задает каталог, в который будут выводиться файлы результатов покрытия. Если238>239> `None`240>241> , результаты для каждого исходного файла помещаются в его каталог.242243Простой пример, демонстрирующий использование программного интерфейса:244245```python246import sys247import trace248249# создать объект Trace, указав, что игнорировать и нужно ли250# выполнять трассировку или подсчёт строк, или и то и другое251tracer = trace.Trace(252    ignoredirs=[sys.prefix, sys.exec_prefix],253    trace=0,254    count=1)255256# запустить новую команду с помощью указанного трассировщика257tracer.run('main()')258259# создать отчёт, поместив вывод в /tmp260r = tracer.results()261r.write_results(show_missing=True, coverdir="/tmp")262```263