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, file, chain).

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

Это сокращенная запись для print_exception(sys.last_exc, limit, file, 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 опущено, вывод записывается в 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)

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

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

traceback.walk_stack(f)

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

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

traceback.walk_tb(tb)

Обходит traceback, следуя 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, в атрибутах класса сохраняются только данные, необходимые методу TracebackException’s format(). В частности, поле __context__ вычисляется только если __cause__ равно None и __suppress_context__ ложно.

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

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

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

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

__cause__

Причина исходного __cause__.

__context__

Контекст исходного __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)

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

Добавлен в версии 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)

Представляет собой один фрейм в стеке отслеживания исключений или стеке, который форматируется или выводится. По желанию может содержать строковое представление локальных переменных фрейма. Если 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.

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

Этот простой пример реализует цикл «чтение-вычисление-вывод», похожий на (но менее полезный, чем) стандартный цикл интерпретатора 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