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

Функции уровня модуля¶Module-Level Functions

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

Выводит до limit записей трассировки стека из объекта traceback 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)¶

Выводит информацию об исключении и записи трассировки стека из объекта traceback 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, представляющий список «предварительно обработанных»\nзаписей трассировки стека, извлечённых из\nобъекта traceback tb. Это полезно\nдля альтернативного форматирования трассировок стека. Необязательный аргумент limit имеет\nто же значение, что и для print_tb(). «Предварительно обработанная» запись\nтрассировки стека – это объект FrameSummary, содержащий атрибуты\nfilename, lineno,\nname и line, представляющие\nинформацию, которая обычно выводится для трассировки стека.

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

Очищает локальные переменные всех фреймов стека в traceback 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 Objects

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

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.12.

__suppress_context__¶

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

__notes__¶

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

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

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.12.

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

Изменено в версии 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.12.

FrameSummary Объекты¶FrameSummary Objects

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

class traceback.FrameSummary(filename, lineno, name, *, lookup_line=True, locals=None, line=None, end_lineno=None, colno=None, end_colno=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.

end_lineno¶

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

colno¶

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

end_colno¶

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

Примеры использования функций уровня модуля¶Examples of Using the Module-Level Functions

Этот простой пример реализует базовый цикл чтение-вычисление-печать, похожий на (но менее полезный, чем) стандартный цикл интерактивного интерпретатора 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¶Examples of Using 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 работает, как и функции уровня модуля
>>> 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 добавляет локальные переменные в кадры стека
>>> 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

>>> # Именованный аргумент *chain* в print() управляет тем, показываются ли цепочки
>>> # исключений.
>>> 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