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):
• после трассировки стека выводятся тип и значение исключения

• если 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 с атрибутами filename, lineno, name и line, представляющими информацию, которая обычно выводится в трассировке стека.

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])

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

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

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

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

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.

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

Класс исходной трассировки.

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)

Сохраняет исключение для последующего отображения. Значения 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()

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

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

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

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

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

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

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',
 '  File "<doctest default[0]>", line 4, in lumberjack\n    bright_side_of_life()\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',
 '  File "<doctest default[0]>", line 4, in lumberjack\n    bright_side_of_life()\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