traceback — Печать или получение обратного хода стека¶

Исходный код: Lib/traceback.py.

Этот модуль предоставляет стандартный интерфейс для извлечения, форматирования и печати трассировки стека программ Python. Он точно имитирует поведение интерпретатора Python при печати трассы стека. Это полезно, когда вы хотите печатать трассировку стека под контролем программы, например, в «обертке» вокруг интерпретатора.

Модуль использует объекты traceback — это тип объекта, который хранится в переменной sys.last_traceback и возвращается как третий элемент из sys.exc_info().

Модуль определяет следующие функции:

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

Выведите до лимита записей трассировки стека из объекта трассировки tb (начиная с кадра вызывающей стороны), если лимит положителен. В противном случае, печатаются последние abs(limit) записи. Если limit опущен или None, печатаются все записи. Если file опущен или None, вывод идет в sys.stderr; иначе это должен быть открытый файл или файлоподобный объект для получения вывода.

Изменено в версии 3.5: Добавлена поддержка отрицательного лимита.

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 игнорируется и выводится из типа значения.

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

traceback.print_exc(limit=None, file=None, chain=True)¶

Это сокращение для print_exception(*sys.exc_info(), limit, file, chain).

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

Это сокращение для print_exception(sys.last_type, sys.last_value, sys.last_traceback, limit, file, chain). В общем случае оно сработает только после того, как исключение достигнет интерактивного приглашения (см. sys.last_type).

traceback.print_stack(f=None, limit=None, file=None)¶

Выведите до лимита записей трассировки стека (начиная с точки вызова), если лимит положителен. В противном случае печатаются последние abs(limit) записи. Если limit опущен или None, печатаются все записи. Необязательный аргумент f может быть использован для указания альтернативного фрейма стека для запуска. Необязательный аргумент file имеет то же значение, что и для print_tb().

Изменено в версии 3.5: Добавлена поддержка отрицательного лимита.

traceback.extract_tb(tb, limit=None)¶

Возвращает объект StackSummary, представляющий список «предварительно обработанных» записей трассировки стека, извлеченных из объекта трассировки tb. Это полезно для альтернативного форматирования трасс стека. Необязательный аргумент limit имеет то же значение, что и для print_tb(). «Предварительно обработанная» запись трассы стека - это объект FrameSummary, содержащий атрибуты filename, lineno, name и line, представляющие информацию, которая обычно выводится для трассы стека. Атрибут line представляет собой строку с удаленными ведущим и последующим пробелами; если источник недоступен, то это None.

traceback.extract_stack(f=None, limit=None)¶

Извлечение необработанного трассировочного отката из текущего кадра стека. Возвращаемое значение имеет тот же формат, что и для extract_tb(). Необязательные аргументы f и limit имеют то же значение, что и для print_stack().

traceback.format_list(extracted_list)¶

Учитывая список кортежей или объектов FrameSummary, возвращаемых extract_tb() или extract_stack(), возвращает список строк, готовых к печати. Каждая строка в полученном списке соответствует элементу с тем же индексом в списке аргументов. Каждая строка заканчивается новой строкой; строки могут содержать и внутренние новые строки, для тех элементов, чья строка исходного текста не является None.

traceback.format_exception_only(exc, /[, value])¶

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

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

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

traceback.format_exception(exc, /, [value, tb, ]limit=None, chain=True)¶

Форматирует трассировку стека и информацию об исключении. Аргументы имеют то же значение, что и соответствующие аргументы команды print_exception(). Возвращаемое значение представляет собой список строк, каждая из которых заканчивается новой строкой, а некоторые содержат внутренние новые строки. Когда эти строки конкатенируются и выводятся на печать, печатается точно такой же текст, как и в print_exception().

Изменено в версии 3.5: Аргумент etype игнорируется и выводится из типа значения.

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

В модуле также определены следующие классы:

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_death()

def bright_side_of_death():
    return tuple()[0]

try:
    lumberjack()
except IndexError:
    exc_type, exc_value, exc_traceback = sys.exc_info()
    print("*** print_tb:")
    traceback.print_tb(exc_traceback, limit=1, file=sys.stdout)
    print("*** print_exception:")
    # exc_type below is ignored on 3.5 and later
    traceback.print_exception(exc_type, exc_value, exc_traceback,
                              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:")
    # exc_type below is ignored on 3.5 and later
    print(repr(traceback.format_exception(exc_type, exc_value,
                                          exc_traceback)))
    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_death()
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_death()
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...>", line 10, in <module>\n    lumberjack()\n',
 '  File "<doctest...>", line 4, in lumberjack\n    bright_side_of_death()\n',
 '  File "<doctest...>", line 7, in bright_side_of_death\n    return tuple()[0]\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_death>]
*** format_tb:
['  File "<doctest...>", line 10, in <module>\n    lumberjack()\n',
 '  File "<doctest...>", line 4, in lumberjack\n    bright_side_of_death()\n',
 '  File "<doctest...>", line 7, in bright_side_of_death\n    return tuple()[0]\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']