traceback — Вывод или получение стека отладки

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

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

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

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

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

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

Выводит информацию об исключении и до limit записей стека отладки из traceback 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 «предварительно обработанных» записей стека вызовов, извлечённых из объекта traceback tb. Это полезно для альтернативного форматирования стеков вызовов. Если limit опущен или None, извлекаются все записи. «Предварительно обработанная» запись стека вызовов — это 4-кортеж (filename, номер строки, имя функции*, текст), представляющий информацию, обычно выводимую для стека вызовов. текст — это строка с удалёнными начальными и конечными пробелами; если исходный код недоступен, он 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)

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

1. Примеры Traceback

Этот простой пример реализует цикл «чтение-вычисление-печать», аналогичный (но менее полезный, чем) стандартному интерактивному интерпретатору 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']