traceback.md
1> **Источник:** https://python-all.ru/3.10/library/traceback.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# [`traceback`](https://python-all.ru/3.10/library/traceback.html#module-traceback) – печать или получение трассировки стека89**Исходный код:** [Lib/traceback.py](https://python-all.ru/src/3.10/Lib/traceback.py)1011---1213Этот модуль предоставляет стандартный интерфейс для извлечения, форматирования и печати трассировок стека программ Python. Он в точности повторяет поведение интерпретатора Python при печати трассировки стека. Это полезно, когда требуется печатать трассировки стека программно, например, в «обёртке» вокруг интерпретатора.1415Модуль использует объекты traceback – это тип объекта, который хранится в переменной [`sys.last_traceback`](https://python-all.ru/3.10/library/sys.html#sys.last_traceback) и возвращается как третий элемент из [`sys.exc_info()`](https://python-all.ru/3.10/library/sys.html#sys.exc_info).1617> **См. также**18>19> **Модуль [`faulthandler`](https://python-all.ru/3.10/library/faulthandler.html#module-faulthandler)**20>21> Используется для явного дампа трассировок Python при сбое, по таймауту или по сигналу пользователя.22>23> **Модуль [`pdb`](https://python-all.ru/3.10/library/pdb.html#module-pdb)**24>25> Интерактивный отладчик исходного кода для программ на Python.2627Модуль определяет следующие функции:2829#### `traceback.print_tb(tb, limit=None, file=None)`3031Печатает до *limit* записей трассировки стека из объекта traceback *tb* (начиная с фрейма вызывающего), если *limit* положительный. В противном случае печатает последние `abs(limit)` записей. Если *limit* опущен или равен `None`, печатаются все записи. Если *file* опущен или равен `None`, вывод направляется в `sys.stderr`; в противном случае это должен быть открытый файл или файлоподобный объект для получения вывода.3233Изменено в версии 3.5: Добавлена поддержка отрицательного значения *limit*.3435#### `traceback.print_exception(exc, /, [value, tb, ]limit=None, file=None, chain=True)`3637Печатает информацию об исключении и записи трассировки стека из объекта traceback *tb* в *file*. Отличается от [`print_tb()`](https://python-all.ru/3.10/library/traceback.html#traceback.print_tb) следующим образом:3839- если *tb* не равен `None`, выводится заголовок `Traceback (most recent call last):`40- он выводит тип исключения и *value* после трассировки стека4142- если *type(value)* равен [`SyntaxError`](https://python-all.ru/3.10/library/exceptions.html#SyntaxError) и *value* имеет соответствующий формат, выводится строка, в которой произошла синтаксическая ошибка, с символом «^», указывающим приблизительную позицию ошибки.4344Начиная с Python 3.10, вместо передачи *value* и *tb* первым аргументом можно передавать объект исключения. Если *value* и *tb* указаны, первый аргумент игнорируется для обеспечения обратной совместимости.4546Необязательный аргумент *limit* имеет то же значение, что и для [`print_tb()`](https://python-all.ru/3.10/library/traceback.html#traceback.print_tb). Если *chain* истинно (по умолчанию), то цепочка исключений (атрибуты `__cause__` или `__context__` исключения) также будет выведена на печать, как это делает сам интерпретатор при печати необработанного исключения.4748Изменено в версии 3.5: Аргумент *etype* игнорируется и определяется по типу *value*.4950Изменено в версии 3.10: Параметр *etype* переименован в *exc* и теперь является только позиционным.5152#### `traceback.print_exc(limit=None, file=None, chain=True)`5354Это сокращение для `print_exception(*sys.exc_info(), limit, file, chain)`.5556#### `traceback.print_last(limit=None, file=None, chain=True)`5758Это сокращение для `print_exception(sys.last_type, sys.last_value, sys.last_traceback, limit, file, chain)`. В общем случае оно будет работать только после того, как исключение достигнет интерактивного приглашения (см. [`sys.last_type`](https://python-all.ru/3.10/library/sys.html#sys.last_type)).5960#### `traceback.print_stack(f=None, limit=None, file=None)`6162Печатает до *limit* записей трассировки стека (начиная с точки вызова), если *limit* положительный. В противном случае печатает последние `abs(limit)` записей. Если *limit* опущен или равен `None`, печатаются все записи. Необязательный аргумент *f* можно использовать для указания альтернативного стекового фрейма для начала. Необязательный аргумент *file* имеет то же значение, что и для [`print_tb()`](https://python-all.ru/3.10/library/traceback.html#traceback.print_tb).6364Изменено в версии 3.5: Добавлена поддержка отрицательного значения *limit*.6566#### `traceback.extract_tb(tb, limit=None)`6768Возвращает объект [`StackSummary`](https://python-all.ru/3.10/library/traceback.html#traceback.StackSummary), представляющий список «предварительно обработанных» записей трассировки стека, извлечённых из объекта traceback *tb*. Полезно для альтернативного форматирования трассировок стека. Необязательный аргумент *limit* имеет то же значение, что и для [`print_tb()`](https://python-all.ru/3.10/library/traceback.html#traceback.print_tb). «Предварительно обработанная» запись трассировки стека – это объект [`FrameSummary`](https://python-all.ru/3.10/library/traceback.html#traceback.FrameSummary), содержащий атрибуты `filename`, `lineno`, `name` и `line`, представляющие информацию, которая обычно печатается для трассировки стека. `line` – это строка с удалёнными начальными и конечными пробелами; если исходный код недоступен, она равна `None`.6970#### `traceback.extract_stack(f=None, limit=None)`7172Извлекает необработанную трассировку из текущего стекового фрейма. Возвращаемое значение имеет тот же формат, что и для [`extract_tb()`](https://python-all.ru/3.10/library/traceback.html#traceback.extract_tb). Необязательные аргументы *f* и *limit* имеют то же значение, что и для [`print_stack()`](https://python-all.ru/3.10/library/traceback.html#traceback.print_stack).7374#### `traceback.format_list(extracted_list)`7576Принимает список кортежей или объектов [`FrameSummary`](https://python-all.ru/3.10/library/traceback.html#traceback.FrameSummary), возвращённых [`extract_tb()`](https://python-all.ru/3.10/library/traceback.html#traceback.extract_tb) или [`extract_stack()`](https://python-all.ru/3.10/library/traceback.html#traceback.extract_stack), и возвращает список строк, готовых к выводу. Каждая строка в результирующем списке соответствует элементу с тем же индексом в исходном списке. Каждая строка заканчивается символом новой строки; строки могут также содержать внутренние переводы строк для тех элементов, чья строка исходного текста не равна `None`.7778#### `traceback.format_exception_only(exc, /[, value])`7980Форматирует часть трассировки, связанную с исключением, используя значение исключения, например, возвращаемое `sys.last_value`. Возвращаемое значение – список строк, каждая из которых заканчивается символом новой строки. Обычно список содержит одну строку; однако для исключений [`SyntaxError`](https://python-all.ru/3.10/library/exceptions.html#SyntaxError) он содержит несколько строк, которые (при печати) отображают подробную информацию о том, где произошла синтаксическая ошибка. Сообщение, указывающее, какое именно исключение произошло, всегда является последней строкой в списке.8182Начиная с Python 3.10, вместо передачи *value* в качестве первого аргумента можно передавать объект исключения. Если передан *value*, первый аргумент игнорируется для обеспечения обратной совместимости.8384Изменено в версии 3.10: Параметр *etype* переименован в *exc* и теперь является только позиционным.8586#### `traceback.format_exception(exc, /, [value, tb, ]limit=None, chain=True)`8788Форматирует трассировку стека и информацию об исключении. Аргументы имеют тот же смысл, что и соответствующие аргументы [`print_exception()`](https://python-all.ru/3.10/library/traceback.html#traceback.print_exception). Возвращаемое значение – список строк, каждая заканчивается символом новой строки, некоторые содержат внутренние переводы строк. При объединении и выводе этих строк печатается в точности тот же текст, что и при вызове [`print_exception()`](https://python-all.ru/3.10/library/traceback.html#traceback.print_exception).8990Изменено в версии 3.5: Аргумент *etype* игнорируется и определяется по типу *value*.9192Изменено в версии 3.10: Поведение и сигнатура этой функции были изменены в соответствии с [`print_exception()`](https://python-all.ru/3.10/library/traceback.html#traceback.print_exception).9394#### `traceback.format_exc(limit=None, chain=True)`9596Аналог `print_exc(limit)`, но возвращает строку вместо вывода в файл.9798#### `traceback.format_tb(tb, limit=None)`99100Сокращение для `format_list(extract_tb(tb, limit))`.101102#### `traceback.format_stack(f=None, limit=None)`103104Сокращение для `format_list(extract_stack(f, limit))`.105106#### `traceback.clear_frames(tb)`107108Очищает локальные переменные всех стековых фреймов в трассировке *tb*, вызывая метод `clear()` каждого объекта фрейма.109110Новое в версии 3.4.111112#### `traceback.walk_stack(f)`113114Обходит стек, следуя `f.f_back`, начиная с заданного фрейма, и порождает фрейм и номер строки для каждого фрейма. Если *f* равен `None`, используется текущий стек. Этот вспомогательный инструмент используется с [`StackSummary.extract()`](https://python-all.ru/3.10/library/traceback.html#traceback.StackSummary.extract).115116Новое в версии 3.5.117118#### `traceback.walk_tb(tb)`119120Обходит трассировку, следуя `tb_next`, и порождает фрейм и номер строки для каждого фрейма. Этот вспомогательный инструмент используется с [`StackSummary.extract()`](https://python-all.ru/3.10/library/traceback.html#traceback.StackSummary.extract).121122Новое в версии 3.5.123124Модуль также определяет следующие классы:125126## [`TracebackException`](https://python-all.ru/3.10/library/traceback.html#traceback.TracebackException) Объекты127128Новое в версии 3.5.129130Объекты [`TracebackException`](https://python-all.ru/3.10/library/traceback.html#traceback.TracebackException) создаются на основе реальных исключений для сохранения данных для последующей печати в облегчённом виде.131132#### `class traceback.TracebackException(exc_type, exc_value, exc_traceback, *, limit=None, lookup_lines=True, capture_locals=False, compact=False)`133134Захватывает исключение для последующего отображения. Параметры *limit*, *lookup\_lines* и *capture\_locals* такие же, как для класса [`StackSummary`](https://python-all.ru/3.10/library/traceback.html#traceback.StackSummary).135136Если *compact* истинно, в атрибутах класса сохраняются только данные, необходимые методу `format` класса [`TracebackException`](https://python-all.ru/3.10/library/traceback.html#traceback.TracebackException). В частности, поле `__context__` вычисляется только если `__cause__` равно `None`, а `__suppress_context__` ложно.137138Обратите внимание, что при захвате локальных переменных они также отображаются в трассировке.139140#### `__cause__`141142[`TracebackException`](https://python-all.ru/3.10/library/traceback.html#traceback.TracebackException) исходного `__cause__`.143144#### `__context__`145146[`TracebackException`](https://python-all.ru/3.10/library/traceback.html#traceback.TracebackException) исходного `__context__`.147148#### `__suppress_context__`149150Значение `__suppress_context__` из исходного исключения.151152#### `stack`153154[`StackSummary`](https://python-all.ru/3.10/library/traceback.html#traceback.StackSummary), представляющий трассировку.155156#### `exc_type`157158Класс исходной обратной трассировки.159160#### `filename`161162Для синтаксических ошибок – имя файла, в котором произошла ошибка.163164#### `lineno`165166Для синтаксических ошибок – номер строки, в которой произошла ошибка.167168#### `end_lineno`169170Для синтаксических ошибок – номер конечной строки, в которой произошла ошибка. Может быть `None`, если отсутствует.171172Новое в версии 3.10.173174#### `text`175176Для синтаксических ошибок – текст, в котором произошла ошибка.177178#### `offset`179180Для синтаксических ошибок – смещение в тексте, где произошла ошибка.181182#### `end_offset`183184Для синтаксических ошибок – конечное смещение в тексте, где произошла ошибка. Может быть `None`, если отсутствует.185186Новое в версии 3.10.187188#### `msg`189190Для синтаксических ошибок – сообщение об ошибке компилятора.191192#### `classmethod from_exception(exc, *, limit=None, lookup_lines=True, capture_locals=False)`193194Захватывает исключение для последующего отображения. Параметры *limit*, *lookup\_lines* и *capture\_locals* такие же, как для класса [`StackSummary`](https://python-all.ru/3.10/library/traceback.html#traceback.StackSummary).195196Обратите внимание, что при захвате локальных переменных они также отображаются в трассировке.197198#### `format(*, chain=True)`199200Форматирует исключение.201202Если *chain* не `True`, то `__cause__` и `__context__` не будут отформатированы.203204Возвращаемое значение – генератор строк, каждая из которых завершается символом новой строки, и некоторые содержат внутренние переводы строк. [`print_exception()`](https://python-all.ru/3.10/library/traceback.html#traceback.print_exception) является обёрткой вокруг этого метода, которая просто выводит строки в файл.205206Сообщение о произошедшем исключении всегда находится в последней строке вывода.207208#### `format_exception_only()`209210Форматирует часть трассировки, относящуюся к исключению.211212Возвращаемое значение – генератор строк, каждая из которых завершается символом новой строки.213214Обычно генератор выдает одну строку; однако для исключений [`SyntaxError`](https://python-all.ru/3.10/library/exceptions.html#SyntaxError) он выдает несколько строк, которые (при печати) отображают подробную информацию о том, где произошла синтаксическая ошибка.215216Сообщение о произошедшем исключении всегда находится в последней строке вывода.217218Изменено в версии 3.10: Добавлен параметр *compact*.219220## [`StackSummary`](https://python-all.ru/3.10/library/traceback.html#traceback.StackSummary) Объекты221222Новое в версии 3.5.223224Объекты [`StackSummary`](https://python-all.ru/3.10/library/traceback.html#traceback.StackSummary) представляют стек вызовов, готовый к форматированию.225226#### `class traceback.StackSummary`227228#### `classmethod extract(frame_gen, *, limit=None, lookup_lines=True, capture_locals=False)`229230Создаёт объект [`StackSummary`](https://python-all.ru/3.10/library/traceback.html#traceback.StackSummary) из генератора фреймов (такого, как возвращается [`walk_stack()`](https://python-all.ru/3.10/library/traceback.html#traceback.walk_stack) или [`walk_tb()`](https://python-all.ru/3.10/library/traceback.html#traceback.walk_tb)).231232Если указан параметр *limit*, из *frame\_gen* берётся только указанное количество фреймов. Если *lookup\_lines* равно `False`, возвращённые объекты [`FrameSummary`](https://python-all.ru/3.10/library/traceback.html#traceback.FrameSummary) ещё не прочитают свои строки, что удешевляет создание [`StackSummary`](https://python-all.ru/3.10/library/traceback.html#traceback.StackSummary) (это может быть полезно, если он, возможно, не будет фактически отформатирован). Если *capture\_locals* равно `True`, локальные переменные в каждом [`FrameSummary`](https://python-all.ru/3.10/library/traceback.html#traceback.FrameSummary) захватываются в виде представления объектов.233234#### `classmethod from_list(a_list)`235236Создает объект [`StackSummary`](https://python-all.ru/3.10/library/traceback.html#traceback.StackSummary) из предоставленного списка объектов [`FrameSummary`](https://python-all.ru/3.10/library/traceback.html#traceback.FrameSummary) или списка кортежей старого стиля. Каждый кортеж должен быть кортежем из 4 элементов: filename, lineno, name, line.237238#### `format()`239240Возвращает список строк, готовых к печати. Каждая строка в результирующем списке соответствует одному фрейму из стека. Каждая строка заканчивается переводом строки; строки могут также содержать внутренние переводы строк для элементов с исходным текстом.241242Для длинных последовательностей одинаковых фреймов и строк сначала показываются первые несколько повторений, а затем сводная строка с указанием точного числа последующих повторений.243244Изменено в версии 3.6: Длинные последовательности повторяющихся фреймов теперь сокращаются.245246## [`FrameSummary`](https://python-all.ru/3.10/library/traceback.html#traceback.FrameSummary) Объекты247248Новое в версии 3.5.249250Объекты [`FrameSummary`](https://python-all.ru/3.10/library/traceback.html#traceback.FrameSummary) представляют один фрейм в traceback.251252#### `class traceback.FrameSummary(filename, lineno, name, lookup_line=True, locals=None, line=None)`253254Представляет один фрейм в traceback или стеке, который форматируется или выводится на печать. При желании может содержать строковое представление локальных переменных фрейма. Если *lookup\_line* равен `False`, исходный код не ищется до тех пор, пока у [`FrameSummary`](https://python-all.ru/3.10/library/traceback.html#traceback.FrameSummary) не будет получен доступ к атрибуту `line` (что также происходит при преобразовании в кортеж). `line` может быть предоставлен напрямую, что полностью предотвратит поиск строк. *locals* – это необязательный словарь локальных переменных; если он указан, представления переменных сохраняются в сводке для последующего отображения.255256## Примеры traceback257258Этот простой пример реализует базовый цикл чтение-вычисление-печать, похожий на (но менее полезный, чем) стандартный цикл интерактивного интерпретатора Python. Для более полной реализации цикла интерпретатора обратитесь к модулю [`code`](https://python-all.ru/3.10/library/code.html#module-code).259260```python261import sys, traceback262263def run_user_code(envdir):264 source = input(">>> ")265 try:266 exec(source, envdir)267 except Exception:268 print("Exception in user code:")269 print("-"*60)270 traceback.print_exc(file=sys.stdout)271 print("-"*60)272273envdir = {}274while True:275 run_user_code(envdir)276```277278Следующий пример демонстрирует различные способы вывода и форматирования исключения и трассировки:279280```python281import sys, traceback282283def lumberjack():284 bright_side_of_life()285286def bright_side_of_life():287 return tuple()[0]288289try:290 lumberjack()291except IndexError:292 exc_type, exc_value, exc_traceback = sys.exc_info()293 print("*** print_tb:")294 traceback.print_tb(exc_traceback, limit=1, file=sys.stdout)295 print("*** print_exception:")296 traceback.print_exception(exc_value, limit=2, file=sys.stdout)297 print("*** print_exc:")298 traceback.print_exc(limit=2, file=sys.stdout)299 print("*** format_exc, first and last line:")300 formatted_lines = traceback.format_exc().splitlines()301 print(formatted_lines[0])302 print(formatted_lines[-1])303 print("*** format_exception:")304 print(repr(traceback.format_exception(exc_value)))305 print("*** extract_tb:")306 print(repr(traceback.extract_tb(exc_traceback)))307 print("*** format_tb:")308 print(repr(traceback.format_tb(exc_traceback)))309 print("*** tb_lineno:", exc_traceback.tb_lineno)310```311312Вывод для примера будет выглядеть примерно так:313314```text315*** print_tb:316 File "<doctest...>", line 10, in <module>317 lumberjack()318*** print_exception:319Traceback (most recent call last):320 File "<doctest...>", line 10, in <module>321 lumberjack()322 File "<doctest...>", line 4, in lumberjack323 bright_side_of_life()324IndexError: tuple index out of range325*** print_exc:326Traceback (most recent call last):327 File "<doctest...>", line 10, in <module>328 lumberjack()329 File "<doctest...>", line 4, in lumberjack330 bright_side_of_life()331IndexError: tuple index out of range332*** format_exc, first and last line:333Traceback (most recent call last):334IndexError: tuple index out of range335*** format_exception:336['Traceback (most recent call last):\n',337 ' File "<doctest...>", line 10, in <module>\n lumberjack()\n',338 ' File "<doctest...>", line 4, in lumberjack\n bright_side_of_life()\n',339 ' File "<doctest...>", line 7, in bright_side_of_life\n return tuple()[0]\n',340 'IndexError: tuple index out of range\n']341*** extract_tb:342[<FrameSummary file <doctest...>, line 10 in <module>>,343 <FrameSummary file <doctest...>, line 4 in lumberjack>,344 <FrameSummary file <doctest...>, line 7 in bright_side_of_life>]345*** format_tb:346[' File "<doctest...>", line 10, in <module>\n lumberjack()\n',347 ' File "<doctest...>", line 4, in lumberjack\n bright_side_of_life()\n',348 ' File "<doctest...>", line 7, in bright_side_of_life\n return tuple()[0]\n']349*** tb_lineno: 10350```351352Следующий пример показывает различные способы вывода и форматирования стека:353354```python355>>> import traceback356>>> def another_function():357... lumberstack()358...359>>> def lumberstack():360... traceback.print_stack()361... print(repr(traceback.extract_stack()))362... print(repr(traceback.format_stack()))363...364>>> another_function()365 File "<doctest>", line 10, in <module>366 another_function()367 File "<doctest>", line 3, in another_function368 lumberstack()369 File "<doctest>", line 6, in lumberstack370 traceback.print_stack()371[('<doctest>', 10, '<module>', 'another_function()'),372 ('<doctest>', 3, 'another_function', 'lumberstack()'),373 ('<doctest>', 7, 'lumberstack', 'print(repr(traceback.extract_stack()))')]374[' File "<doctest>", line 10, in <module>\n another_function()\n',375 ' File "<doctest>", line 3, in another_function\n lumberstack()\n',376 ' File "<doctest>", line 8, in lumberstack\n print(repr(traceback.format_stack()))\n']377```378379Этот последний пример демонстрирует несколько последних функций форматирования:380381```pycon382>>> import traceback383>>> traceback.format_list([('spam.py', 3, '<module>', 'spam.eggs()'),384... ('eggs.py', 42, 'eggs', 'return "bacon"')])385[' File "spam.py", line 3, in <module>\n spam.eggs()\n',386 ' File "eggs.py", line 42, in eggs\n return "bacon"\n']387>>> an_error = IndexError('tuple index out of range')388>>> traceback.format_exception_only(type(an_error), an_error)389['IndexError: tuple index out of range\n']390```391