`traceback` — Вывести или получить обратную трассировку стека¶

Источник: Lib/traceback.py

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

В модуле используются traceback objects — это объекты типа types.TracebackType, которые присваиваются полю __traceback__ экземпляров BaseException.

См.также

Модуль faulthandler: Используется для явного сброса трассировки Python, при ошибке, после таймаута или по сигналу пользователя.
Модуль pdb: Интерактивный отладчик исходного кода для программ на Python.

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

traceback.print_tb(tb, limit=None, file=None)¶: Выведите до лимита записей трассировки стека, начиная с traceback object tb (начиная с кадра вызывающей стороны), если limit положителен. В противном случае печатаются последние записи abs(limit). Если limit опущено или None, выводятся все записи. Если file опущен или None, вывод идет в sys.stderr; в противном случае должен быть открыт file или file-like object для получения вывода.

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

traceback.print_exception(exc, /, [value, tb, ]limit=None, file=None, chain=True)¶

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

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

Если type(value) равно SyntaxError и value имеет соответствующий формат, то печатается строка, в которой произошла синтаксическая ошибка, с кареткой, указывающей на примерное местоположение ошибки.

Начиная с Python 3.10, вместо передачи value и tb в качестве первого аргумента может быть передан объект исключения. Если переданы value и tb, первый аргумент игнорируется для обеспечения обратной совместимости.

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

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

Изменено в версии 3.10: Параметр etype был переименован в exc и теперь является только позиционным.

traceback.print_exc(limit=None, file=None, chain=True)¶: Это сокращение для print_exception(sys.exception(), limit, file, chain).

traceback.print_last(limit=None, file=None, chain=True)¶: Это сокращение для print_exception(sys.last_exc, limit, file, chain). В общем случае оно сработает только после того, как исключение достигнет интерактивной подсказки (см. sys.last_exc).

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

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

traceback.extract_tb(tb, limit=None)¶: Возвращает объект StackSummary, представляющий список «предварительно обработанных» записей трассировки стека, извлеченных из traceback object tb. Это полезно для альтернативного форматирования трасс стека. Необязательный аргумент limit имеет то же значение, что и для print_tb(). Запись «предварительно обработанной» трассы стека - это объект FrameSummary, содержащий атрибуты filename, lineno, name и line, представляющие информацию, которая обычно выводится для трассы стека.

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

traceback.format_list(extracted_list)¶: Получив список кортежей или объектов FrameSummary, возвращаемых функциями extract_tb() или extract_stack(), верните список строк, готовых к печати. Каждая строка в полученном списке соответствует элементу с тем же индексом в списке аргументов. Каждая строка заканчивается новой строкой; строки могут содержать и внутренние новые строки для тех элементов, чья строка исходного текста не является None.

traceback.format_exception_only(exc, /, [value, ]*, show_group=False)¶

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

Начиная с Python 3.10, вместо передачи value в качестве первого аргумента может быть передан объект исключения. Если передано значение, первый аргумент игнорируется в целях обеспечения обратной совместимости.

Если show_group имеет значение True, а исключение является экземпляром BaseExceptionGroup, вложенные исключения также включаются, рекурсивно, с отступом относительно глубины вложенности.

Изменено в версии 3.10: Параметр etype был переименован в exc и теперь является только позиционным.

Изменено в версии 3.11: Теперь возвращаемый список включает все notes, связанные с исключением.

Изменено в версии 3.13: Добавлен параметр show_group.

traceback.format_exception(exc, /, [value, tb, ]limit=None, chain=True)¶: Форматирует трассировку стека и информацию об исключении. Аргументы имеют то же значение, что и соответствующие аргументы в print_exception(). Возвращаемое значение - это список строк, каждая из которых заканчивается новой строкой, а некоторые содержат внутренние новые строки. Когда эти строки объединяются и выводятся на печать, печатается точно такой же текст, как и в print_exception().

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

Изменено в версии 3.10: Поведение и сигнатура этой функции были изменены, чтобы соответствовать print_exception().

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)¶: Очищает локальные переменные всех кадров стека в traceback tb путем вызова метода clear() каждого frame object.

Added in version 3.4.

traceback.walk_stack(f)¶: Пройтись по стеку, следующему за f.f_back от заданного кадра, выдавая номер кадра и строки для каждого кадра. Если f равно None, используется текущий стек. Этот помощник используется вместе с StackSummary.extract().

Added in version 3.5.

traceback.walk_tb(tb)¶: Проведите трассировку после tb_next, указав номер кадра и строки для каждого кадра. Этот помощник используется вместе с StackSummary.extract().

Added in version 3.5.

В модуле также определены следующие классы:

`TracebackException` Объекты¶

Added in version 3.5.

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

class traceback.TracebackException(exc_type, exc_value, exc_traceback, *, limit=None, lookup_lines=True, capture_locals=False, compact=False, max_group_width=15, max_group_depth=10)¶

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

Если значение compact равно true, то в атрибутах класса сохраняются только те данные, которые требуются для метода TracebackException format(). В частности, поле __context__ вычисляется только в том случае, если __cause__ равно None и __suppress_context__ равно false.

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

max_group_width и max_group_depth управляют форматированием групп исключений (см. BaseExceptionGroup). Глубина относится к уровню вложенности группы, а ширина - к размеру массива исключений одной группы исключений. Форматированный вывод усекается при превышении любого из этих пределов.

Изменено в версии 3.10: Добавлен параметр компактность.

Изменено в версии 3.11: Добавлены параметры max_group_width и max_group_depth.

__cause__¶: TracebackException исходного __cause__.

__context__¶: TracebackException исходного __context__.

exceptions¶: Если self представляет собой ExceptionGroup, то в этом поле хранится список экземпляров TracebackException, представляющих вложенные исключения. В противном случае это None.

Added in version 3.11.

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

__notes__¶: Значение __notes__ из исходного исключения или None, если у исключения нет примечаний. Если это не None, то оно форматируется в обратном пути после строки исключения.

Added in version 3.11.

stack¶: Значение StackSummary, представляющее откат трассы.

exc_type¶: Класс исходного трассировщика.

Не рекомендуется, начиная с версии 3.13.

exc_type_str¶: Строковое отображение класса исходного исключения.

Added in version 3.13.

filename¶: Для синтаксических ошибок - имя файла, в котором произошла ошибка.

lineno¶: Для синтаксических ошибок - номер строки, в которой произошла ошибка.

end_lineno¶: Для синтаксических ошибок - номер конечной строки, в которой произошла ошибка. Может быть None, если не присутствует.

Added in version 3.10.

text¶: Для синтаксических ошибок - текст, в котором произошла ошибка.

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

end_offset¶: Для синтаксических ошибок - смещение конца текста, в котором произошла ошибка. Может иметь значение None, если оно отсутствует.

Added in version 3.10.

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

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

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

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

print(*, file=None, chain=True)¶: Печать в файл (по умолчанию sys.stderr) информации об исключениях, возвращенной командой format().

Added in version 3.11.

format(*, chain=True)¶

Отформатируйте исключение.

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

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

format_exception_only(*, show_group=False)¶

Форматируйте часть исключения в обратном пути.

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

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

Если show_group имеет значение True, а исключение является экземпляром BaseExceptionGroup, вложенные исключения также включаются, рекурсивно, с отступом относительно глубины вложенности.

Изменено в версии 3.11: Исключения notes теперь включаются в вывод.

Изменено в версии 3.13: Добавлен параметр show_group.

`StackSummary` Объекты¶

Added in version 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 захватываются как представления объектов.

Изменено в версии 3.12: Исключения, вызванные из repr() на локальной переменной (когда capture_locals имеет значение True), больше не передаются вызывающей стороне.

classmethod from_list(a_list)¶: Создайте объект StackSummary из предоставленного списка объектов FrameSummary или списка кортежей старого образца. Каждый кортеж должен быть 4-кортежем, элементами которого являются filename, lineno, name, line.

format()¶

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

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

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

format_frame_summary(frame_summary)¶: Возвращает строку для печати одного из frames, находящихся в стеке. Этот метод вызывается для каждого объекта FrameSummary, который должен быть распечатан StackSummary.format(). Если он возвращает None, кадр не выводится.

Added in version 3.11.

`FrameSummary` Объекты¶

Added in version 3.5.

Объект FrameSummary представляет собой один frame в traceback.

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

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

Экземпляры FrameSummary имеют следующие атрибуты:

filename¶: Имя файла исходного кода для этого кадра. Эквивалентно обращению к f.f_code.co_filename на frame object f.

lineno¶: Номер строки исходного кода для этого кадра.

name¶: Эквивалентно доступу к f.f_code.co_name на frame object f.

line¶: Строка, представляющая исходный код этого кадра, с удаленными ведущими и завершающими пробелами. Если исходный код недоступен, то это None.

Примеры возврата к трассировке¶

Этот простой пример реализует базовый цикл read-eval-print, похожий (но менее полезный, чем) на стандартный цикл интерактивного интерпретатора 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_life()

def bright_side_of_life():
    return tuple()[0]

try:
    lumberjack()
except IndexError:
    exc = sys.exception()
    print("*** print_tb:")
    traceback.print_tb(exc.__traceback__, limit=1, file=sys.stdout)
    print("*** print_exception:")
    traceback.print_exception(exc, 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:")
    print(repr(traceback.format_exception(exc)))
    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_life()
    ~~~~~~~~~~~~~~~~~~~^^
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_life()
    ~~~~~~~~~~~~~~~~~~~^^
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 default[0]>", line 10, in <module>\n    lumberjack()\n    ~~~~~~~~~~^^\n',
 '  File "<doctest default[0]>", line 4, in lumberjack\n    bright_side_of_life()\n    ~~~~~~~~~~~~~~~~~~~^^\n',
 '  File "<doctest default[0]>", line 7, in bright_side_of_life\n    return tuple()[0]\n           ~~~~~~~^^^\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_life>]
*** format_tb:
['  File "<doctest default[0]>", line 10, in <module>\n    lumberjack()\n    ~~~~~~~~~~^^\n',
 '  File "<doctest default[0]>", line 4, in lumberjack\n    bright_side_of_life()\n    ~~~~~~~~~~~~~~~~~~~^^\n',
 '  File "<doctest default[0]>", line 7, in bright_side_of_life\n    return tuple()[0]\n           ~~~~~~~^^^\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']

`traceback` — Вывести или получить обратную трассировку стека¶

`TracebackException` Объекты¶

`StackSummary` Объекты¶

`FrameSummary` Объекты¶

Примеры возврата к трассировке¶

Оглавление

Предыдущий раздел

Следующий раздел

traceback — Вывести или получить обратную трассировку стека¶

TracebackException Объекты¶

StackSummary Объекты¶

FrameSummary Объекты¶

Примеры возврата к трассировке¶

`traceback` — Вывести или получить обратную трассировку стека¶

`TracebackException` Объекты¶

`StackSummary` Объекты¶

`FrameSummary` Объекты¶