traceback — вывод или получение трассировки стека

Функции уровня модуля

traceback.print_tb(tb, limit=None, file=None)

Выводит до limit записей трассировки стека из объекта трассировки tb (начиная с кадра вызывающей стороны), если значение limit положительное. В противном случае выводит последние abs(limit) записей. Если limit не указан или равен None, выводятся все записи. Если file не указан или равен None, вывод направляется в sys.stderr; в противном случае это должен быть открытый файловый объект или объект, подобный файлу, принимающий вывод.

Примечание

Параметр limit имеет смысл, отличный от смысла sys.tracebacklimit. Отрицательное значение limit соответствует положительному значению sys.tracebacklimit, тогда как поведение, соответствующее положительному значению limit, невозможно получить с помощью sys.tracebacklimit.

Изменено в версии 3.5: Добавлена поддержка отрицательного значения limit.

traceback.print_exception(exc, /, [value, tb, ]limit=None, file=None, chain=True)

Выводит сведения об исключении и записи трассировки стека из объекта трассировки tb в file. Эта функция отличается от print_tb() следующим:

• если tb не равен None, выводится заголовок Traceback (most recent call last):
• после трассировки стека выводятся тип исключения и value

• если type(value) равен SyntaxError и value имеет подходящий формат, выводится строка, в которой произошла синтаксическая ошибка, с указателем на приблизительное место ошибки.

Начиная с Python 3.10 вместо передачи value и tb первым аргументом можно передать объект исключения. Если указаны value и tb, первый аргумент игнорируется для обратной совместимости.

Необязательный аргумент limit имеет то же значение, что и для print_tb(). Если chain имеет значение true (по умолчанию), также выводятся связанные исключения (атрибуты __cause__ или __context__ исключения), как это делает сам интерпретатор при выводе необработанного исключения.

Изменено в версии 3.5: Аргумент etype игнорируется; его значение определяется по типу value.

Изменено в версии 3.10: Параметр etype переименован в exc и теперь является только позиционным.

traceback.print_exc(limit=None, file=None, chain=True)

Это сокращённая запись для print_exception(sys.exception(), limit=limit, file=file, chain=chain).

traceback.print_last(limit=None, file=None, chain=True)

Это сокращённая запись для print_exception(sys.last_exc, limit=limit, file=file, chain=chain). Как правило, функция работает только после того, как исключение достигло интерактивной подсказки (см. sys.last_exc).

traceback.print_stack(f=None, limit=None, file=None)

Выводит до limit записей трассировки стека (начиная с точки вызова), если значение limit положительное. В противном случае выводит последние abs(limit) записей. Если limit не указан или равен None, выводятся все записи. Необязательный аргумент f позволяет указать другой кадр стека, с которого следует начать. Необязательный аргумент file имеет то же значение, что и для print_tb().

Изменено в версии 3.5: Добавлена поддержка отрицательного значения limit.

traceback.extract_tb(tb, limit=None)

Возвращает объект StackSummary, представляющий список предварительно обработанных записей трассировки стека, извлечённых из объекта трассировки tb. Это полезно для альтернативного форматирования трассировок стека. Необязательный аргумент limit имеет то же значение, что и для print_tb(). Предварительно обработанная запись трассировки стека — это объект FrameSummary с атрибутами, представляющими сведения, которые обычно выводятся для трассировки стека.

traceback.extract_stack(f=None, limit=None)

Извлекает необработанную трассировку из текущего кадра стека. Возвращаемое значение имеет тот же формат, что и у extract_tb(). Необязательные аргументы f и limit имеют то же значение, что и для print_stack().

traceback.print_list(extracted_list, file=None)

Выводит список кортежей, возвращаемый функцией extract_tb() или extract_stack(), в виде отформатированной трассировки стека в указанный файл. Если file равен None, вывод записывается в sys.stderr.

traceback.format_list(extracted_list)

Получив список кортежей или объектов FrameSummary, возвращаемый функцией extract_tb() или extract_stack(), функция возвращает список строк, готовых к выводу. Каждая строка в результирующем списке соответствует элементу с тем же индексом в списке аргументов. Каждая строка заканчивается символом новой строки; строки также могут содержать внутренние символы новой строки, если текст исходной строки не равен None.

traceback.format_exception_only(exc, /, [value, ]*, show_group=False)

Форматирует часть трассировки, относящуюся к исключению, используя значение исключения, например значение, возвращаемое sys.last_exc. Возвращаемое значение — список строк, каждая из которых заканчивается символом новой строки. Список содержит сообщение исключения, обычно представляющее собой одну строку; однако для исключений SyntaxError он содержит несколько строк, которые при выводе показывают подробные сведения о месте возникновения синтаксической ошибки. После сообщения в списке следуют notes исключения.

Начиная с Python 3.10 вместо передачи value первым аргументом можно передать объект исключения. Если указан value, первый аргумент игнорируется для обратной совместимости.

Если show_group равен True, а исключение является экземпляром BaseExceptionGroup, вложенные исключения также включаются в вывод рекурсивно, с отступом, соответствующим глубине вложенности.

Изменено в версии 3.10: Параметр etype переименован в exc и теперь является только позиционным.

Изменено в версии 3.11: Теперь возвращаемый список также содержит все notes, присоединённые к исключению.

Изменено в версии 3.13: Добавлен параметр show_group.

traceback.format_exception(exc, /, [value, tb, ]limit=None, chain=True)

Форматирует трассировку стека и сведения об исключении. Аргументы имеют то же значение, что и соответствующие аргументы print_exception(). Возвращаемое значение — список строк, каждая из которых заканчивается символом новой строки; некоторые строки содержат внутренние символы новой строки. При объединении и выводе этих строк получается в точности тот же текст, что и при вызове print_exception().

Изменено в версии 3.5: Аргумент etype игнорируется; его значение определяется по типу value.

Изменено в версии 3.10: Поведение и сигнатура этой функции изменены для соответствия print_exception().

traceback.format_exc(limit=None, chain=True)

Подобна print_exc(limit), но возвращает строку вместо вывода в файл.

traceback.format_tb(tb, limit=None)

Сокращённая запись для format_list(extract_tb(tb, limit)).

traceback.format_stack(f=None, limit=None)

Сокращённая запись для format_list(extract_stack(f, limit)).

traceback.clear_frames(tb)

Очищает локальные переменные всех кадров стека в трассировке tb, вызывая метод clear() каждого объекта кадра.

Добавлено в версии 3.4.

traceback.walk_stack(f)

Обходит стек, следуя по f.f_back от указанного кадра и возвращая кадр и номер строки для каждого кадра. Если f равен None, используется текущий стек. Этот вспомогательный метод используется вместе с StackSummary.extract().

Добавлено в версии 3.5.

Изменено в версии 3.14: Ранее эта функция возвращала генератор, который обходил стек при первой итерации. Теперь возвращаемый генератор представляет состояние стека на момент вызова walk_stack.

traceback.walk_tb(tb)

Обходит трассировку, следуя по tb_next и возвращая кадр и номер строки для каждого кадра. Этот вспомогательный метод используется вместе с StackSummary.extract().

Добавлено в версии 3.5.

TracebackException Объекты

Объекты TracebackException создаются на основе реальных исключений для сохранения данных, необходимых для последующего вывода. Они позволяют хранить эту информацию более компактно, не удерживая ссылки на объекты трассировки и кадра. Кроме того, они предоставляют больше возможностей для настройки вывода, чем описанные выше функции уровня модуля.

class traceback.TracebackException(exc_type, exc_value, exc_traceback, *, limit=None, lookup_lines=True, capture_locals=False, compact=False, max_group_width=15, max_group_depth=10)

Сохраняет исключение для последующего отображения. Аргументы limit, lookup_lines и capture_locals имеют то же значение, что и для класса StackSummary.

Если compact имеет значение true, в атрибутах класса сохраняются только данные, необходимые методу format() класса TracebackException. В частности, поле __context__ вычисляется только в том случае, если __cause__ равен None, а __suppress_context__ имеет значение false.

Обратите внимание: если локальные переменные сохраняются, они также отображаются в трассировке.

max_group_width и max_group_depth управляют форматированием групп исключений (см. BaseExceptionGroup). Глубина соответствует уровню вложенности группы, а ширина — размеру массива исключений одной группы. Отформатированный вывод обрезается при превышении любого из этих ограничений.

Изменено в версии 3.10: Добавлен параметр compact.

Изменено в версии 3.11: Добавлены параметры max_group_width и max_group_depth.

__cause__

Объект TracebackException исходного __cause__.

__context__

Объект TracebackException исходного __context__.

exceptions

Если self представляет ExceptionGroup, это поле содержит список экземпляров TracebackException, представляющих вложенные исключения. В противном случае оно равно None.

Добавлено в версии 3.11.

__suppress_context__

Значение __suppress_context__ исходного исключения.

__notes__

Значение __notes__ исходного исключения или None, если у исключения нет примечаний. Если значение не равно None, оно выводится в трассировке после строки исключения.

Добавлено в версии 3.11.

stack

Объект StackSummary, представляющий трассировку.

exc_type

Класс исходного исключения.

Устарело с версии 3.13.

exc_type_str

Строковое представление класса исходного исключения.

Добавлено в версии 3.13.

filename

Для синтаксических ошибок — имя файла, в котором произошла ошибка.

lineno

Для синтаксических ошибок — номер строки, в которой произошла ошибка.

end_lineno

Для синтаксических ошибок — номер последней строки, в которой произошла ошибка. Может быть равен None, если отсутствует.

Добавлено в версии 3.10.

text

Для синтаксических ошибок — текст, в котором произошла ошибка.

offset

Для синтаксических ошибок — смещение в тексте, указывающее место ошибки.

end_offset

Для синтаксических ошибок — конечное смещение в тексте, указывающее место ошибки. Может быть равным None, если отсутствует.

Добавлено в версии 3.10.

msg

Для синтаксических ошибок — сообщение об ошибке компилятора.

classmethod from_exception(exc, *, limit=None, lookup_lines=True, capture_locals=False, compact=False, max_group_width=15, max_group_depth=10)

Сохраняет исключение для последующего отображения. Аргументы limit, lookup_lines и capture_locals имеют то же значение, что и для класса StackSummary.

Обратите внимание: если локальные переменные сохраняются, они также отображаются в трассировке.

print(*, file=None, chain=True)

Выводит в file (по умолчанию sys.stderr) сведения об исключении, возвращаемые функцией format().

Добавлено в версии 3.11.

format(*, chain=True)

Форматирует исключение.

Если chain не равен True, __cause__ и __context__ форматироваться не будут.

Возвращаемое значение — генератор строк, каждая из которых заканчивается символом новой строки; некоторые строки содержат внутренние символы новой строки. print_exception() — это обёртка над данным методом, которая просто выводит строки в файл.

format_exception_only(*, show_group=False)

Форматирует часть трассировки, относящуюся к исключению.

Возвращаемое значение — генератор строк, каждая из которых заканчивается символом новой строки.

Если show_group равен False, генератор выводит сообщение исключения, а затем его примечания (если они есть). Сообщение исключения обычно представляет собой одну строку; однако для исключений SyntaxError оно состоит из нескольких строк, которые при выводе показывают подробные сведения о месте возникновения синтаксической ошибки.

Если show_group равен True, а исключение является экземпляром BaseExceptionGroup, вложенные исключения также включаются в вывод рекурсивно, с отступом, соответствующим глубине вложенности.

Изменено в версии 3.11: Теперь в вывод включаются notes исключения.

Изменено в версии 3.13: Добавлен параметр show_group.

StackSummary Объекты

Объекты StackSummary представляют собой стек вызовов, готовый к форматированию.

class traceback.StackSummary

classmethod extract(frame_gen, *, limit=None, lookup_lines=True, capture_locals=False)

Создаёт объект StackSummary из генератора кадров (например, возвращаемого функцией walk_stack() или walk_tb()).

Если задан параметр limit, из frame_gen берётся только указанное количество кадров. Если lookup_lines равен False, возвращаемые объекты FrameSummary ещё не будут содержать прочитанные строки, что снижает затраты на создание объекта StackSummary (это может быть полезно, если он в итоге не будет форматироваться). Если capture_locals равен True, локальные переменные каждого FrameSummary сохраняются в виде представлений объектов.

Изменено в версии 3.12: Исключения, возникающие при вызове repr() для локальной переменной (если capture_locals равен True), больше не передаются вызывающему коду.

classmethod from_list(a_list)

Создаёт объект StackSummary из переданного списка объектов FrameSummary или списка кортежей старого формата. Каждый кортеж должен содержать 4 элемента: filename, lineno, name и line.

format()

Возвращает список строк, готовых к выводу. Каждая строка в результирующем списке соответствует одному кадру стека. Каждая строка заканчивается символом новой строки; строки также могут содержать внутренние переводы строк, если в них есть строки исходного кода.

Для длинных последовательностей одинаковых кадров и строк исходного кода показываются первые несколько повторений, за которыми следует сводная строка с точным количеством оставшихся повторений.

Изменено в версии 3.6: Длинные последовательности повторяющихся кадров теперь сокращаются.

format_frame_summary(frame_summary)

Возвращает строку для вывода одного из кадров, входящих в стек. Этот метод вызывается для каждого объекта FrameSummary, который должен быть выведен функцией StackSummary.format(). Если он возвращает None, кадр не включается в вывод.

Добавлено в версии 3.11.

FrameSummary Объекты

Объект FrameSummary представляет один кадр в трассировке.

class traceback.FrameSummary(filename, lineno, name, *, lookup_line=True, locals=None, line=None, end_lineno=None, colno=None, end_colno=None)

Представляет один кадр в трассировке или стеке, который форматируется или выводится. При необходимости он может содержать строковое представление локальных переменных кадра. Если lookup_line равен False, исходный код не ищется, пока у FrameSummary не будет запрошен атрибут line (это также происходит при преобразовании в tuple). line можно передать напрямую, и в таком случае поиск строк вообще не выполняется. locals — необязательное отображение локальных переменных; если оно передано, представления переменных сохраняются в сводке для последующего отображения.

Экземпляры FrameSummary имеют следующие атрибуты:

filename

Имя файла с исходным кодом для этого кадра. Эквивалентно обращению к f.f_code.co_filename у объекта кадра f.

lineno

Номер строки исходного кода для этого кадра.

name

Эквивалентно обращению к f.f_code.co_name у объекта кадра f.

line

Строка с исходным кодом для этого кадра без начальных и конечных пробелов. Если исходный код недоступен, значение равно None.

end_lineno

Номер последней строки исходного кода для этого кадра. По умолчанию имеет значение lineno; нумерация начинается с 1.

Изменено в версии 3.13: Значение по умолчанию изменено с None на lineno.

colno

Номер столбца исходного кода для этого кадра. По умолчанию имеет значение None; нумерация начинается с 0.

end_colno

Номер последнего столбца исходного кода для этого кадра. По умолчанию имеет значение None; нумерация начинается с 0.

Примеры использования функций уровня модуля

В этом простом примере реализован базовый цикл «чтение — вычисление — вывод», похожий на стандартный интерактивный цикл интерпретатора Python (но менее функциональный). Более полную реализацию цикла интерпретатора см. в модуле code.

import sys, traceback

def run_user_code(envdir):
    source = input(">>> ")
    try:
        exec(source, envdir)
    except Exception:
        print("Exception in user code:")
        print("-"*60)
        traceback.print_exc(file=sys.stdout)
        print("-"*60)

envdir = {}
while True:
    run_user_code(envdir)

В следующем примере показаны различные способы вывода и форматирования исключения и трассировки:

import sys, traceback

def lumberjack():
    bright_side_of_life()

def bright_side_of_life():
    return tuple()[0]

try:
    lumberjack()
except IndexError as exc:
    print("*** print_tb:")
    traceback.print_tb(exc.__traceback__, limit=1, file=sys.stdout)
    print("*** print_exception:")
    traceback.print_exception(exc, limit=2, file=sys.stdout)
    print("*** print_exc:")
    traceback.print_exc(limit=2, file=sys.stdout)
    print("*** format_exc, first and last line:")
    formatted_lines = traceback.format_exc().splitlines()
    print(formatted_lines[0])
    print(formatted_lines[-1])
    print("*** format_exception:")
    print(repr(traceback.format_exception(exc)))
    print("*** extract_tb:")
    print(repr(traceback.extract_tb(exc.__traceback__)))
    print("*** format_tb:")
    print(repr(traceback.format_tb(exc.__traceback__)))
    print("*** tb_lineno:", exc.__traceback__.tb_lineno)

Вывод этого примера будет выглядеть примерно так:

*** print_tb:
  File "<doctest...>", line 10, in <module>
    lumberjack()
    ~~~~~~~~~~^^
*** print_exception:
Traceback (most recent call last):
  File "<doctest...>", line 10, in <module>
    lumberjack()
    ~~~~~~~~~~^^
  File "<doctest...>", line 4, in lumberjack
    bright_side_of_life()
    ~~~~~~~~~~~~~~~~~~~^^
IndexError: tuple index out of range
*** print_exc:
Traceback (most recent call last):
  File "<doctest...>", line 10, in <module>
    lumberjack()
    ~~~~~~~~~~^^
  File "<doctest...>", line 4, in lumberjack
    bright_side_of_life()
    ~~~~~~~~~~~~~~~~~~~^^
IndexError: tuple index out of range
*** format_exc, first and last line:
Traceback (most recent call last):
IndexError: tuple index out of range
*** format_exception:
['Traceback (most recent call last):\n',
 '  File "<doctest default[0]>", line 10, in <module>\n    lumberjack()\n    ~~~~~~~~~~^^\n',
 '  File "<doctest default[0]>", line 4, in lumberjack\n    bright_side_of_life()\n    ~~~~~~~~~~~~~~~~~~~^^\n',
 '  File "<doctest default[0]>", line 7, in bright_side_of_life\n    return tuple()[0]\n           ~~~~~~~^^^\n',
 'IndexError: tuple index out of range\n']
*** extract_tb:
[<FrameSummary file <doctest...>, line 10 in <module>>,
 <FrameSummary file <doctest...>, line 4 in lumberjack>,
 <FrameSummary file <doctest...>, line 7 in bright_side_of_life>]
*** format_tb:
['  File "<doctest default[0]>", line 10, in <module>\n    lumberjack()\n    ~~~~~~~~~~^^\n',
 '  File "<doctest default[0]>", line 4, in lumberjack\n    bright_side_of_life()\n    ~~~~~~~~~~~~~~~~~~~^^\n',
 '  File "<doctest default[0]>", line 7, in bright_side_of_life\n    return tuple()[0]\n           ~~~~~~~^^^\n']
*** tb_lineno: 10

В следующем примере показаны различные способы вывода и форматирования стека:

>>> import traceback
>>> def another_function():
...     lumberstack()
...
>>> def lumberstack():
...     traceback.print_stack()
...     print(repr(traceback.extract_stack()))
...     print(repr(traceback.format_stack()))
...
>>> another_function()
  File "<doctest>", line 10, in <module>
    another_function()
  File "<doctest>", line 3, in another_function
    lumberstack()
  File "<doctest>", line 6, in lumberstack
    traceback.print_stack()
[('<doctest>', 10, '<module>', 'another_function()'),
 ('<doctest>', 3, 'another_function', 'lumberstack()'),
 ('<doctest>', 7, 'lumberstack', 'print(repr(traceback.extract_stack()))')]
['  File "<doctest>", line 10, in <module>\n    another_function()\n',
 '  File "<doctest>", line 3, in another_function\n    lumberstack()\n',
 '  File "<doctest>", line 8, in lumberstack\n    print(repr(traceback.format_stack()))\n']

В последнем примере показаны остальные функции форматирования:

>>> import traceback
>>> traceback.format_list([('spam.py', 3, '<module>', 'spam.eggs()'),
...                        ('eggs.py', 42, 'eggs', 'return "bacon"')])
['  File "spam.py", line 3, in <module>\n    spam.eggs()\n',
 '  File "eggs.py", line 42, in eggs\n    return "bacon"\n']
>>> an_error = IndexError('tuple index out of range')
>>> traceback.format_exception_only(an_error)
['IndexError: tuple index out of range\n']

Примеры использования TracebackException

Вспомогательный класс предоставляет дополнительные возможности:

>>> import sys
>>> from traceback import TracebackException
>>>
>>> def lumberjack():
...     bright_side_of_life()
...
>>> def bright_side_of_life():
...     t = "bright", "side", "of", "life"
...     return t[5]
...
>>> try:
...     lumberjack()
... except IndexError as e:
...     exc = e
...
>>> try:
...     try:
...         lumberjack()
...     except:
...         1/0
... except Exception as e:
...     chained_exc = e
...
>>> # limit works as with the module-level functions
>>> TracebackException.from_exception(exc, limit=-2).print()
Traceback (most recent call last):
  File "<python-input-1>", line 6, in lumberjack
    bright_side_of_life()
    ~~~~~~~~~~~~~~~~~~~^^
  File "<python-input-1>", line 10, in bright_side_of_life
    return t[5]
           ~^^^
IndexError: tuple index out of range

>>> # capture_locals adds local variables in frames
>>> TracebackException.from_exception(exc, limit=-2, capture_locals=True).print()
Traceback (most recent call last):
  File "<python-input-1>", line 6, in lumberjack
    bright_side_of_life()
    ~~~~~~~~~~~~~~~~~~~^^
  File "<python-input-1>", line 10, in bright_side_of_life
    return t[5]
           ~^^^
    t = ("bright", "side", "of", "life")
IndexError: tuple index out of range

>>> # The *chain* kwarg to print() controls whether chained
>>> # exceptions are displayed
>>> TracebackException.from_exception(chained_exc).print()
Traceback (most recent call last):
  File "<python-input-19>", line 4, in <module>
    lumberjack()
    ~~~~~~~~~~^^
  File "<python-input-8>", line 7, in lumberjack
    bright_side_of_life()
    ~~~~~~~~~~~~~~~~~~~^^
  File "<python-input-8>", line 11, in bright_side_of_life
    return t[5]
           ~^^^
IndexError: tuple index out of range

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "<python-input-19>", line 6, in <module>
    1/0
    ~^~
ZeroDivisionError: division by zero

>>> TracebackException.from_exception(chained_exc).print(chain=False)
Traceback (most recent call last):
  File "<python-input-19>", line 6, in <module>
    1/0
    ~^~
ZeroDivisionError: division by zero