traceback – печать или получение трассировки стека¶traceback – Print or retrieve a stack traceback

TracebackException Объекты¶TracebackException Objects

Объекты 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 format(). В частности, поле __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()¶

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

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

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

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

StackSummary Объекты¶StackSummary Objects

Объекты 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 захватываются в виде представления объектов.

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 Objects

Объект FrameSummary представляет отдельный фрейм в трассировке.

class traceback.FrameSummary(filename, lineno, name, lookup_line=True, locals=None, line=None)¶

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

Примеры traceback¶Traceback Examples

Этот простой пример реализует базовый цикл чтение-вычисление-печать, похожий на (но менее полезный, чем) стандартный цикл интерактивного интерпретатора 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:
    exc = sys.exception()
    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(type(an_error), an_error)
['IndexError: tuple index out of range\n']