29.9. traceback – Вывод или получение трассировки стека¶traceback – Print or retrieve a stack traceback

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

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

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

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

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

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

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

traceback.print_exception(etype, value, tb, limit=None, file=None, chain=True)¶

Печатает информацию об исключении и записи трассировки стека из объекта traceback tb в file. Отличается от print_tb() следующим образом:

• если tb не равен None, выводится заголовок Traceback (most recent call last):

• выводит исключение etype и value после трассировки стека

• если type(value) равен SyntaxError и value имеет соответствующий формат, выводится строка, в которой произошла синтаксическая ошибка, с символом «^», указывающим приблизительную позицию ошибки.

Необязательный аргумент limit имеет то же значение, что и для print_tb(). Если chain истинно (по умолчанию), то цепочка исключений (атрибуты __cause__ или __context__ исключения) также будет выведена на печать, как это делает сам интерпретатор при печати необработанного исключения.

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

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

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

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

traceback.extract_tb(tb, limit=None)¶

Возвращает объект StackSummary, представляющий список «предварительно обработанных» записей трассировки стека, извлечённых из объекта traceback 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(etype, value)¶

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

traceback.format_exception(etype, value, tb, limit=None, chain=True)¶

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

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

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:")
    # тип исключения ниже игнорируется начиная с Python 3.5
    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:")
    # тип исключения ниже игнорируется начиная с Python 3.5
    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']