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 истинно (по умолчанию), также выводятся связанные исключения (атрибуты __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, ]*, show_group=False)

Форматирует часть трассировки, относящуюся к исключению, используя значение исключения, например значение, предоставляемое sys.last_value. Возвращаемое значение — список строк, каждая из которых заканчивается символом новой строки. Список содержит сообщение исключения, обычно представляющее собой одну строку; однако для исключений 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.

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 истинно, в атрибутах класса сохраняются только данные, необходимые методу 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)

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