traceback — Распечатать или получить трассировку стека


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

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

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

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

Печать до limit записей трассировки стека из объекта трассировки 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)

Печать информации об исключениях и записей трассировки стека из объекта трейсбэка 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, представляющий список «предварительно обработанных» записей трассировки стека, извлеченных из объекта трейсбэк 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.

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

Объекты TracebackException

Добавлено в версии 3.5.

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__ не будут отформатированы.

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

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

format_exception_only()

Отформатировать часть исключения трейсбэк.

Возвращает значение - это генератор строки, каждая из которых заканчивается новой строкой.

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

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

Объекты StackSummary

Добавлено в версии 3.5.

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 кортежем с именем файла, lineno, именем, линией в качестве элементов.

format()

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

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

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

Объекты FrameSummary

Добавлено в версии 3.5.

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

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

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

Примеры Traceback

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