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 равно true (по умолчанию), то вызываются исключения, связанные с текущим (атрибуты __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.

Модуль также определяет следующие классы:

29.9.1. Объекты TracebackException

TracebackException создаются из фактических исключений, чтобы захватить данные для последующего вывода легким способом.

class traceback.TracebackException(exc_type, exc_value, exc_traceback, *, limit=None, lookup_lines=True, capture_locals=False)

Захват исключения для последующего рендеринга. limit, lookup_lines и capture_locals аналогичны классу StackSummary.

Обратите внимание, что при захвате локальных переменных они также отображаются в трассировке.

__cause__

Объект TracebackException исходного __cause__.

__context__

Объект TracebackException исходного __context__.

__suppress_context__

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

stack

StackSummary, представляющий трассировку.

exc_type

Класс исходной трассировки.

filename

Для синтаксических ошибок — имя файла, где произошла ошибка.

lineno

Для синтаксических ошибок — номер строки, где произошла ошибка.

text

Для синтаксических ошибок — текст, где произошла ошибка.

offset

Для синтаксических ошибок — смещение в тексте, где произошла ошибка.

msg

Для синтаксических ошибок — сообщение об ошибке компилятора.

classmethod from_exception(exc, *, limit=None, lookup_lines=True, capture_locals=False)

Захват исключения для последующего рендеринга. limit, lookup_lines и capture_locals аналогичны классу StackSummary.

Обратите внимание, что при захвате локальных переменных они также отображаются в трассировке.

format(*, chain=True)

Форматирование исключения.

Если chain не True, __cause__ и __context__ не будут отформатированы.

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

Сообщение об возникшем исключении всегда является последней строкой вывода.

format_exception_only()

Форматирование части исключения в трассировке.

Возвращаемое значение — генератор строк, каждая заканчивается новой строкой.

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

Сообщение об возникшем исключении всегда является последней строкой вывода.

29.9.2. Объекты StackSummary

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

classmethod from_list(a_list)

Создание объекта StackSummary из предоставленного списка объектов FrameSummary или списков кортежей старого стиля. Каждый кортеж должен быть 4-кортежем с файлом, номером строки, именем и строкой как элементами.

format()

Возвращает список строк, готовых для вывода. Каждая строка в результирующем списке соответствует одному кадру из стека. Каждая строка заканчивается новой строкой; строки могут также содержать внутренние новые строки для тех элементов, у которых есть строки исходного текста.

Для длинных последовательностей одинакового кадра и строки отображаются первые несколько повторений, а затем строка сводки, указывающая точное количество последующих повторений.

Изменено в версии 3.6: Длинные последовательности повторяющихся кадров теперь сокращаются.

29.9.3. Объекты FrameSummary

FrameSummary объекты представляют один кадр в трассировке.

class traceback.FrameSummary(filename, lineno, name, lookup_line=True, locals=None, line=None)

Представляет один кадр в трассировке или стеке, который форматируется или выводится. Он может необязательно содержать строковое представление локальных переменных кадра. Если lookup_line равно False, исходный код не ищется до тех пор, пока у FrameSummary не будет обращен доступ к атрибуту line (что также происходит при приведении его к кортежу). line может быть предоставлен напрямую и предотвратит поиск строк вообще. locals — это необязательный словарь локальных переменных; при его предоставлении представления переменных хранятся в сводке для последующего отображения.

29.9.4. Примеры трассировки

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