traceback.md
1> **Источник:** https://python-all.ru/3.5/library/traceback.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 29.9. [`traceback`](https://python-all.ru/3.5/library/traceback.html#module-traceback) – Вывод или получение трассировки стека89**Исходный код:** [Lib/traceback.py](https://python-all.ru/src/3.5/Lib/traceback.py)1011---1213Этот модуль предоставляет стандартный интерфейс для извлечения, форматирования и печати трассировок стека программ Python. Он в точности повторяет поведение интерпретатора Python при печати трассировки стека. Это полезно, когда требуется печатать трассировки стека программно, например, в «обёртке» вокруг интерпретатора.1415Модуль использует объекты traceback – это тип объекта, который хранится в переменной [`sys.last_traceback`](https://python-all.ru/3.5/library/sys.html#sys.last_traceback) и возвращается как третий элемент из [`sys.exc_info()`](https://python-all.ru/3.5/library/sys.html#sys.exc_info).1617Модуль определяет следующие функции:1819#### `traceback.print_tb(tb, limit=None, file=None)`2021Печатает до *limit* записей трассировки стека из объекта traceback *tb* (начиная с фрейма вызывающего), если *limit* положительный. В противном случае печатает последние `abs(limit)` записей. Если *limit* опущен или равен `None`, печатаются все записи. Если *file* опущен или равен `None`, вывод направляется в `sys.stderr`; в противном случае это должен быть открытый файл или файлоподобный объект для получения вывода.2223Изменено в версии 3.5: Добавлена поддержка отрицательного значения *limit*.2425#### `traceback.print_exception(etype, value, tb, limit=None, file=None, chain=True)`2627Печатает информацию об исключении и записи трассировки стека из объекта traceback *tb* в *file*. Отличается от [`print_tb()`](https://python-all.ru/3.5/library/traceback.html#traceback.print_tb) следующим образом:2829- если *tb* не равен `None`, выводится заголовок `Traceback (most recent call last):`30- выводит исключение *etype* и *value* после трассировки стека31- если *type(value)* равен [`SyntaxError`](https://python-all.ru/3.5/library/exceptions.html#SyntaxError) и *value* имеет соответствующий формат, выводится строка, в которой произошла синтаксическая ошибка, с символом «^», указывающим приблизительную позицию ошибки.3233Необязательный аргумент *limit* имеет то же значение, что и для [`print_tb()`](https://python-all.ru/3.5/library/traceback.html#traceback.print_tb). Если *chain* истинно (по умолчанию), то цепочка исключений (атрибуты `__cause__` или `__context__` исключения) также будет выведена на печать, как это делает сам интерпретатор при печати необработанного исключения.3435Изменено в версии 3.5: Аргумент *etype* игнорируется и определяется по типу *value*.3637#### `traceback.print_exc(limit=None, file=None, chain=True)`3839Это сокращение для `print_exception(*sys.exc_info(), limit, file, chain)`.4041#### `traceback.print_last(limit=None, file=None, chain=True)`4243Это сокращение для `print_exception(sys.last_type, sys.last_value, sys.last_traceback, limit, file, chain)`. В общем случае оно будет работать только после того, как исключение достигнет интерактивного приглашения (см. [`sys.last_type`](https://python-all.ru/3.5/library/sys.html#sys.last_type)).4445#### `traceback.print_stack(f=None, limit=None, file=None)`4647Печатает до *limit* записей трассировки стека (начиная с точки вызова), если *limit* положительный. В противном случае печатает последние `abs(limit)` записей. Если *limit* опущен или равен `None`, печатаются все записи. Необязательный аргумент *f* можно использовать для указания альтернативного стекового фрейма для начала. Необязательный аргумент *file* имеет то же значение, что и для [`print_tb()`](https://python-all.ru/3.5/library/traceback.html#traceback.print_tb).4849Изменено в версии 3.5: Добавлена поддержка отрицательного значения *limit*.5051#### `traceback.extract_tb(tb, limit=None)`5253Возвращает список «предварительно обработанных» записей трассировки стека, извлечённых из объекта трассировки *tb*. Это полезно для альтернативного форматирования трассировок стека. Необязательный аргумент *limit* имеет тот же смысл, что и в [`print_tb()`](https://python-all.ru/3.5/library/traceback.html#traceback.print_tb). «Предварительно обработанная» запись трассировки стека – это кортеж из 4 элементов (*filename*, *line number*, *function name*, *text*), представляющий информацию, которая обычно выводится для трассировки стека. *text* – это строка с удалёнными начальными и конечными пробелами; если исходный код недоступен, она равна `None`.5455#### `traceback.extract_stack(f=None, limit=None)`5657Извлекает необработанную трассировку из текущего стекового фрейма. Возвращаемое значение имеет тот же формат, что и для [`extract_tb()`](https://python-all.ru/3.5/library/traceback.html#traceback.extract_tb). Необязательные аргументы *f* и *limit* имеют то же значение, что и для [`print_stack()`](https://python-all.ru/3.5/library/traceback.html#traceback.print_stack).5859#### `traceback.format_list(extracted_list)`6061Принимает список кортежей, возвращаемый функциями [`extract_tb()`](https://python-all.ru/3.5/library/traceback.html#traceback.extract_tb) или [`extract_stack()`](https://python-all.ru/3.5/library/traceback.html#traceback.extract_stack), и возвращает список строк, готовых к выводу. Каждая строка в результирующем списке соответствует элементу с тем же индексом в списке аргументов. Каждая строка завершается символом новой строки; строки могут также содержать внутренние символы новой строки для тех элементов, строка исходного текста которых не равна `None`.6263#### `traceback.format_exception_only(etype, value)`6465Форматирует часть трассировки стека, относящуюся к исключению. Аргументами являются тип и значение исключения, такие как возвращаются `sys.last_type` и `sys.last_value`. Возвращаемое значение – список строк, каждая из которых заканчивается символом новой строки. Обычно, список содержит одну строку; однако для исключений [`SyntaxError`](https://python-all.ru/3.5/library/exceptions.html#SyntaxError) он содержит несколько строк, которые (при печати) отображают подробную информацию о том, где произошла синтаксическая ошибка. Сообщение, указывающее, какое именно исключение произошло, всегда является последней строкой в списке.6667#### `traceback.format_exception(etype, value, tb, limit=None, chain=True)`6869Форматирует трассировку стека и информацию об исключении. Аргументы имеют тот же смысл, что и соответствующие аргументы [`print_exception()`](https://python-all.ru/3.5/library/traceback.html#traceback.print_exception). Возвращаемое значение – список строк, каждая заканчивается символом новой строки, некоторые содержат внутренние переводы строк. При объединении и выводе этих строк печатается в точности тот же текст, что и при вызове [`print_exception()`](https://python-all.ru/3.5/library/traceback.html#traceback.print_exception).7071Изменено в версии 3.5: Аргумент *etype* игнорируется и определяется по типу *value*.7273#### `traceback.format_exc(limit=None, chain=True)`7475Аналог `print_exc(limit)`, но возвращает строку вместо вывода в файл.7677#### `traceback.format_tb(tb, limit=None)`7879Сокращение для `format_list(extract_tb(tb, limit))`.8081#### `traceback.format_stack(f=None, limit=None)`8283Сокращение для `format_list(extract_stack(f, limit))`.8485#### `traceback.clear_frames(tb)`8687Очищает локальные переменные всех стековых фреймов в трассировке *tb*, вызывая метод `clear()` каждого объекта фрейма.8889Новое в версии 3.4.9091#### `traceback.walk_stack(f)`9293Обходит стек, следуя `f.f_back`, начиная с заданного фрейма, и порождает фрейм и номер строки для каждого фрейма. Если *f* равен `None`, используется текущий стек. Этот вспомогательный инструмент используется с [`StackSummary.extract()`](https://python-all.ru/3.5/library/traceback.html#traceback.StackSummary.extract).9495Новое в версии 3.5.9697#### `traceback.walk_tb(tb)`9899Обходит трассировку, следуя `tb_next`, и порождает фрейм и номер строки для каждого фрейма. Этот вспомогательный инструмент используется с [`StackSummary.extract()`](https://python-all.ru/3.5/library/traceback.html#traceback.StackSummary.extract).100101Новое в версии 3.5.102103Модуль также определяет следующие классы:104105## 29.9.1. [`TracebackException`](https://python-all.ru/3.5/library/traceback.html#traceback.TracebackException) Объекты106107Новое в версии 3.5.108109Объекты [`TracebackException`](https://python-all.ru/3.5/library/traceback.html#traceback.TracebackException) создаются на основе реальных исключений для сохранения данных для последующей печати в облегчённом виде.110111#### `class traceback.TracebackException(exc_type, exc_value, exc_traceback, *, limit=None, lookup_lines=True, capture_locals=False)`112113Захватывает исключение для последующего отображения. Параметры *limit*, *lookup\_lines* и *capture\_locals* такие же, как для класса [`StackSummary`](https://python-all.ru/3.5/library/traceback.html#traceback.StackSummary).114115Обратите внимание, что при захвате локальных переменных они также отображаются в трассировке.116117#### `__cause__`118119[`TracebackException`](https://python-all.ru/3.5/library/traceback.html#traceback.TracebackException) исходного `__cause__`.120121#### `__context__`122123[`TracebackException`](https://python-all.ru/3.5/library/traceback.html#traceback.TracebackException) исходного `__context__`.124125#### `__suppress_context__`126127Значение `__suppress_context__` из исходного исключения.128129#### `stack`130131[`StackSummary`](https://python-all.ru/3.5/library/traceback.html#traceback.StackSummary), представляющий трассировку.132133#### `exc_type`134135Класс исходной обратной трассировки.136137#### `filename`138139Для синтаксических ошибок – имя файла, в котором произошла ошибка.140141#### `lineno`142143Для синтаксических ошибок – номер строки, в которой произошла ошибка.144145#### `text`146147Для синтаксических ошибок – текст, в котором произошла ошибка.148149#### `offset`150151Для синтаксических ошибок – смещение в тексте, где произошла ошибка.152153#### `msg`154155Для синтаксических ошибок – сообщение об ошибке компилятора.156157#### `classmethod from_exception(exc, *, limit=None, lookup_lines=True, capture_locals=False)`158159Захватывает исключение для последующего отображения. Параметры *limit*, *lookup\_lines* и *capture\_locals* такие же, как для класса [`StackSummary`](https://python-all.ru/3.5/library/traceback.html#traceback.StackSummary).160161Обратите внимание, что при захвате локальных переменных они также отображаются в трассировке.162163#### `format(*, chain=True)`164165Форматирует исключение.166167Если *chain* не `True`, то `__cause__` и `__context__` не будут отформатированы.168169Возвращаемое значение – генератор строк, каждая из которых завершается символом новой строки, и некоторые содержат внутренние переводы строк. [`print_exception()`](https://python-all.ru/3.5/library/traceback.html#traceback.print_exception) является обёрткой вокруг этого метода, которая просто выводит строки в файл.170171Сообщение о произошедшем исключении всегда находится в последней строке вывода.172173#### `format_exception_only()`174175Форматирует часть трассировки, относящуюся к исключению.176177Возвращаемое значение – генератор строк, каждая из которых завершается символом новой строки.178179Обычно генератор выдает одну строку; однако для исключений [`SyntaxError`](https://python-all.ru/3.5/library/exceptions.html#SyntaxError) он выдает несколько строк, которые (при печати) отображают подробную информацию о том, где произошла синтаксическая ошибка.180181Сообщение о произошедшем исключении всегда находится в последней строке вывода.182183## 29.9.2. [`StackSummary`](https://python-all.ru/3.5/library/traceback.html#traceback.StackSummary) Объекты184185Новое в версии 3.5.186187Объекты [`StackSummary`](https://python-all.ru/3.5/library/traceback.html#traceback.StackSummary) представляют стек вызовов, готовый к форматированию.188189#### `class traceback.StackSummary`190191#### `classmethod extract(frame_gen, *, limit=None, lookup_lines=True, capture_locals=False)`192193Создаёт объект [`StackSummary`](https://python-all.ru/3.5/library/traceback.html#traceback.StackSummary) из генератора фреймов (такого, как возвращается [`walk_stack()`](https://python-all.ru/3.5/library/traceback.html#traceback.walk_stack) или [`walk_tb()`](https://python-all.ru/3.5/library/traceback.html#traceback.walk_tb)).194195Если указан параметр *limit*, из *frame\_gen* берётся только указанное количество фреймов. Если *lookup\_lines* равно `False`, возвращённые объекты [`FrameSummary`](https://python-all.ru/3.5/library/traceback.html#traceback.FrameSummary) ещё не прочитают свои строки, что удешевляет создание [`StackSummary`](https://python-all.ru/3.5/library/traceback.html#traceback.StackSummary) (это может быть полезно, если он, возможно, не будет фактически отформатирован). Если *capture\_locals* равно `True`, локальные переменные в каждом [`FrameSummary`](https://python-all.ru/3.5/library/traceback.html#traceback.FrameSummary) захватываются в виде представления объектов.196197#### `classmethod from_list(a_list)`198199Создаёт объект [`StackSummary`](https://python-all.ru/3.5/library/traceback.html#traceback.StackSummary) из переданного списка кортежей старого образца. Каждый кортеж должен быть кортежем из 4 элементов: filename, lineno, name, line.200201## 29.9.3. [`FrameSummary`](https://python-all.ru/3.5/library/traceback.html#traceback.FrameSummary) Объекты202203Новое в версии 3.5.204205Объекты [`FrameSummary`](https://python-all.ru/3.5/library/traceback.html#traceback.FrameSummary) представляют один фрейм в traceback.206207#### `class traceback.FrameSummary(filename, lineno, name, lookup_line=True, locals=None, line=None)`208209Представляет один фрейм в traceback или стеке, который форматируется или выводится на печать. При желании может содержать строковое представление локальных переменных фрейма. Если *lookup\_line* равен `False`, исходный код не ищется до тех пор, пока у [`FrameSummary`](https://python-all.ru/3.5/library/traceback.html#traceback.FrameSummary) не будет получен доступ к атрибуту `line` (что также происходит при преобразовании в кортеж). `line` может быть предоставлен напрямую, что полностью предотвратит поиск строк. *locals* – это необязательный словарь локальных переменных; если он указан, представления переменных сохраняются в сводке для последующего отображения.210211## 29.9.4. Примеры использования traceback212213Этот простой пример реализует базовый цикл чтение-вычисление-печать, похожий на (но менее полезный, чем) стандартный цикл интерактивного интерпретатора Python. Для более полной реализации цикла интерпретатора обратитесь к модулю [`code`](https://python-all.ru/3.5/library/code.html#module-code).214215```python216import sys, traceback217218def run_user_code(envdir):219 source = input(">>> ")220 try:221 exec(source, envdir)222 except Exception:223 print("Exception in user code:")224 print("-"*60)225 traceback.print_exc(file=sys.stdout)226 print("-"*60)227228envdir = {}229while True:230 run_user_code(envdir)231```232233Следующий пример демонстрирует различные способы вывода и форматирования исключения и трассировки:234235```python236import sys, traceback237238def lumberjack():239 bright_side_of_death()240241def bright_side_of_death():242 return tuple()[0]243244try:245 lumberjack()246except IndexError:247 exc_type, exc_value, exc_traceback = sys.exc_info()248 print("*** print_tb:")249 traceback.print_tb(exc_traceback, limit=1, file=sys.stdout)250 print("*** print_exception:")251 # тип исключения ниже игнорируется начиная с Python 3.5252 traceback.print_exception(exc_type, exc_value, exc_traceback,253 limit=2, file=sys.stdout)254 print("*** print_exc:")255 traceback.print_exc(limit=2, file=sys.stdout)256 print("*** format_exc, first and last line:")257 formatted_lines = traceback.format_exc().splitlines()258 print(formatted_lines[0])259 print(formatted_lines[-1])260 print("*** format_exception:")261 # тип исключения ниже игнорируется начиная с Python 3.5262 print(repr(traceback.format_exception(exc_type, exc_value,263 exc_traceback)))264 print("*** extract_tb:")265 print(repr(traceback.extract_tb(exc_traceback)))266 print("*** format_tb:")267 print(repr(traceback.format_tb(exc_traceback)))268 print("*** tb_lineno:", exc_traceback.tb_lineno)269```270271Вывод для примера будет выглядеть примерно так:272273```text274*** print_tb:275 File "<doctest...>", line 10, in <module>276 lumberjack()277*** print_exception:278Traceback (most recent call last):279 File "<doctest...>", line 10, in <module>280 lumberjack()281 File "<doctest...>", line 4, in lumberjack282 bright_side_of_death()283IndexError: tuple index out of range284*** print_exc:285Traceback (most recent call last):286 File "<doctest...>", line 10, in <module>287 lumberjack()288 File "<doctest...>", line 4, in lumberjack289 bright_side_of_death()290IndexError: tuple index out of range291*** format_exc, first and last line:292Traceback (most recent call last):293IndexError: tuple index out of range294*** format_exception:295['Traceback (most recent call last):\n',296 ' File "<doctest...>", line 10, in <module>\n lumberjack()\n',297 ' File "<doctest...>", line 4, in lumberjack\n bright_side_of_death()\n',298 ' File "<doctest...>", line 7, in bright_side_of_death\n return tuple()[0]\n',299 'IndexError: tuple index out of range\n']300*** extract_tb:301[<FrameSummary file <doctest...>, line 10 in <module>>,302 <FrameSummary file <doctest...>, line 4 in lumberjack>,303 <FrameSummary file <doctest...>, line 7 in bright_side_of_death>]304*** format_tb:305[' File "<doctest...>", line 10, in <module>\n lumberjack()\n',306 ' File "<doctest...>", line 4, in lumberjack\n bright_side_of_death()\n',307 ' File "<doctest...>", line 7, in bright_side_of_death\n return tuple()[0]\n']308*** tb_lineno: 10309```310311Следующий пример показывает различные способы вывода и форматирования стека:312313```python314>>> import traceback315>>> def another_function():316... lumberstack()317...318>>> def lumberstack():319... traceback.print_stack()320... print(repr(traceback.extract_stack()))321... print(repr(traceback.format_stack()))322...323>>> another_function()324 File "<doctest>", line 10, in <module>325 another_function()326 File "<doctest>", line 3, in another_function327 lumberstack()328 File "<doctest>", line 6, in lumberstack329 traceback.print_stack()330[('<doctest>', 10, '<module>', 'another_function()'),331 ('<doctest>', 3, 'another_function', 'lumberstack()'),332 ('<doctest>', 7, 'lumberstack', 'print(repr(traceback.extract_stack()))')]333[' File "<doctest>", line 10, in <module>\n another_function()\n',334 ' File "<doctest>", line 3, in another_function\n lumberstack()\n',335 ' File "<doctest>", line 8, in lumberstack\n print(repr(traceback.format_stack()))\n']336```337338Этот последний пример демонстрирует несколько последних функций форматирования:339340```pycon341>>> import traceback342>>> traceback.format_list([('spam.py', 3, '<module>', 'spam.eggs()'),343... ('eggs.py', 42, 'eggs', 'return "bacon"')])344[' File "spam.py", line 3, in <module>\n spam.eggs()\n',345 ' File "eggs.py", line 42, in eggs\n return "bacon"\n']346>>> an_error = IndexError('tuple index out of range')347>>> traceback.format_exception_only(type(an_error), an_error)348['IndexError: tuple index out of range\n']349```350