Документация Python неофициальный перевод
Содержание страницы

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

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

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

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

traceback.print_tb(tb[, limit[, file]])

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

traceback.print_exception(etype, value, tb[, limit[, file]])

Печатает информацию об исключении и до limit записей трассировки стека из объекта трассировки tb в file. Эта функция отличается от print_tb() следующим: (1) если tb не None, сначала печатается заголовок Traceback (most recent call last):; (2) после трассировки стека печатаются тип исключения etype и значение value; (3) если etype равен SyntaxError и value имеет подходящий формат, печатается строка, в которой произошла синтаксическая ошибка, с курсором, указывающим примерное положение ошибки.

traceback.print_exc([limit[, file]])

Это сокращение для print_exception(sys.exc_type, sys.exc_value, sys.exc_traceback, limit, file). (Фактически он использует sys.exc_info() для получения той же информации потокобезопасным способом, вместо использования устаревших переменных.)

traceback.format_exc([limit])

Аналог print_exc(limit), но возвращает строку вместо вывода в файл.

Новое в версии 2.4.

traceback.print_last([limit[, file]])

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

traceback.print_stack([f[, limit[, file]]])

Эта функция печатает трассировку стека от точки вызова. Необязательный аргумент f можно использовать для указания альтернативного кадра стека, с которого начать. Необязательные аргументы limit и file имеют тот же смысл, что и для print_exception().

traceback.extract_tb(tb[, limit])

Возвращает список до limit «предварительно обработанных» записей трассировки стека, извлечённых из объекта трассировки tb. Полезен для альтернативного форматирования трассировок стека. Если limit опущен или равен None, извлекаются все записи. «Предварительно обработанная» запись трассировки стека – это кортеж из 4 элементов: (filename, line number, function name*, text), представляющий информацию, которая обычно печатается для трассировки стека. text – это строка с удалёнными начальными и конечными пробелами; если исходный код недоступен, он равен None.

traceback.extract_stack([f[, limit]])

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

traceback.format_list(extracted_list)

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

traceback.format_exception_only(etype, value)

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

traceback.format_exception(etype, value, tb[, limit])

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

traceback.format_tb(tb[, limit])

Сокращение для format_list(extract_tb(tb, limit)).

traceback.format_stack([f[, limit]])

Сокращение для format_list(extract_stack(f, limit)).

traceback.tb_lineno(tb)

Эта функция возвращает текущий номер строки, установленный в объекте трассировки. Эта функция была необходима, потому что в версиях Python до 2.3, когда -O флаг передавался Python, tb.tb_lineno не обновлялся корректно. В версиях после 2.3 эта функция не нужна.

28.10.1. Примеры трассировкиTraceback Examples

Этот простой пример реализует базовый цикл чтение-вычисление-печать, похожий на (но менее полезный, чем) стандартный цикл интерактивного интерпретатора Python. Для более полной реализации цикла интерпретатора обратитесь к модулю code.

import sys, traceback

def run_user_code(envdir):
    source = raw_input(">>> ")
    try:
        exec source in envdir
    except:
        print "Exception in user code:"
        print '-'*60
        traceback.print_exc(file=sys.stdout)
        print '-'*60

envdir = {}
while 1:
    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:"
    traceback.print_exception(exc_type, exc_value, exc_traceback,
                              limit=2, file=sys.stdout)
    print "*** print_exc:"
    traceback.print_exc()
    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_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:
[('<doctest...>', 10, '<module>', 'lumberjack()'),
 ('<doctest...>', 4, 'lumberjack', 'bright_side_of_death()'),
 ('<doctest...>', 7, 'bright_side_of_death', 'return tuple()[0]')]
*** 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']