bdb — Фреймворк отладчика

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

---

Модуль bdb выполняет основные функции отладчика, такие как установка точек останова или управление выполнением через отладчик.

Определено следующее исключение:

exception bdb.BdbQuit

Исключение, вызванное классом Bdb для выхода из отладчика.

Модуль bdb также определяет два класса:

class bdb.Breakpoint(self, file, line, temporary=False, cond=None, funcname=None)

Этот класс реализует временные точки останова, подсчет игнорирования, отключение и (повторное) включение, а также условные сигналы.

Точки останова индексируются по номерам в списке bpbynumber и по парам (file, line) в bplist. Первая указывает на один экземпляр класса Breakpoint. Вторая указывает на список таких экземпляров, поскольку в одной строке может быть более одной точки останова.

При создании точки останова связанный с ней file name должен быть в канонической форме. Если задана funcname, точка останова hit будет засчитана при выполнении первой строки этой функции. Точка останова conditional всегда засчитывается как hit.

У экземпляров Breakpoint есть следующие методы:

deleteMe()

Удаление точки останова из списка, связанного с файлом/линией. Если это последняя точка останова в данной позиции, то удаляется и запись для файла/линии.

enable()

Пометьте точку останова как включенную.

disable()

Пометить точку останова как отключенную.

bpformat()

Возвращает строку со всей информацией о точке останова, красиво отформатированную:

• Номер точки останова.

• Временный статус (del или keep).

• Положение файла/линии.

• Состояние разрыва.

• Количество раз игнорирования.

• Количество ударов.

Added in version 3.2.

bpprint(out=None)

Выведите вывод bpformat() в файл out, или, если это None, в стандартный вывод.

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

file

Имя файла Breakpoint.

line

Номер строки Breakpoint внутри file.

temporary

True, если Breakpoint на (файл, строка) является временным.

cond

Условие для оценки Breakpoint в (файл, строка).

funcname

Имя функции, определяющее, будет ли введен Breakpoint при входе в функцию.

enabled

True, если включен Breakpoint.

bpbynumber

Числовой индекс для одного экземпляра Breakpoint.

bplist

Словарь экземпляров Breakpoint, индексированных кортежами (file, line).

ignore

Количество раз для игнорирования Breakpoint.

hits

Подсчитывает количество попаданий в Breakpoint.

class bdb.Bdb(skip=None)

Класс Bdb действует как общий базовый класс отладчика Python.

Этот класс заботится о деталях средства трассировки; производный класс должен реализовать взаимодействие с пользователем. В качестве примера можно привести стандартный класс отладчика (pdb.Pdb).

Аргумент skip, если он задан, должен представлять собой итерацию шаблонов имен модулей в стиле glob. Отладчик не будет переходить к кадрам, возникшим в модуле, который соответствует одному из этих шаблонов. Считается ли кадр происходящим из определенного модуля, определяется значением __name__ в глобалах кадров.

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

Следующие методы Bdb обычно не нужно переопределять.

canonic(filename)

Возвращает каноническую форму имени filename.

Для реальных имен файлов канонической формой является зависящая от операционной системы форма case-normalized absolute path. Имя файла с угловыми скобками, например "<stdin>", созданное в интерактивном режиме, возвращается без изменений.

reset()

Установите для атрибутов botframe, stopframe, returnframe и quitting значения, готовые для начала отладки.

trace_dispatch(frame, event, arg)

Эта функция устанавливается в качестве функции трассировки отлаженных кадров. Ее возвращаемое значение - новая функция трассировки (в большинстве случаев это она сама).

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

• "line": Будет выполнена новая строка кода.

• "call": Сейчас будет вызвана функция или введен другой блок кода.

• "return": Функция или другой блок кода вот-вот вернется.

• "exception": Произошло исключение.

• "c_call": Сейчас будет вызвана функция C.

• "c_return": Вернулась функция C.

• "c_exception": Функция C вызвала исключение.

Для событий Python вызываются специализированные функции (см. ниже). Для событий на языке C никаких действий не производится.

Параметр arg зависит от предыдущего события.

Дополнительные сведения о функции трассировки см. в документации к sys.settrace(). Дополнительные сведения об объектах кода и фрейма см. в Стандартная иерархия типов.

dispatch_line(frame)

Если отладчик должен остановиться на текущей строке, вызовите метод user_line() (который должен быть переопределен в подклассах). Вызовите исключение BdbQuit, если установлен флаг quitting (который может быть установлен из user_line()). Возвращает ссылку на метод trace_dispatch() для дальнейшей трассировки в этой области видимости.

dispatch_call(frame, arg)

Если отладчик должен остановиться на этом вызове функции, вызовите метод user_call() (который должен быть переопределен в подклассах). Вызовите исключение BdbQuit, если установлен флаг quitting (который может быть установлен из user_call()). Возвращает ссылку на метод trace_dispatch() для дальнейшей трассировки в этой области видимости.

dispatch_return(frame, arg)

Если отладчик должен остановиться на возврате этой функции, вызовите метод user_return() (который должен быть переопределен в подклассах). Вызовите исключение BdbQuit, если установлен флаг quitting (который может быть установлен из user_return()). Возвращает ссылку на метод trace_dispatch() для дальнейшей трассировки в этой области видимости.

dispatch_exception(frame, arg)

Если отладчик должен остановиться на этом исключении, вызывается метод user_exception() (который должен быть переопределен в подклассах). Вызывает исключение BdbQuit, если установлен флаг quitting (который может быть установлен из user_exception()). Возвращает ссылку на метод trace_dispatch() для дальнейшей трассировки в этой области видимости.

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

is_skipped_line(module_name)

Возвращает True, если имя_модуля соответствует любому шаблону пропуска.

stop_here(frame)

Возвращает True, если кадр находится ниже начального кадра в стеке.

break_here(frame)

Верните True, если для этой строки существует эффективная точка останова.

Проверьте, существует ли и действует ли точка останова строки или функции. Удалите временные точки останова, основываясь на информации из effective().

break_anywhere(frame)

Возвращает True, если для имени файла кадр существует какая-либо точка останова.

Производные классы должны переопределять эти методы, чтобы получить контроль над работой отладчика.

user_call(frame, argument_list)

Вызывается из dispatch_call(), если прерывание может остановиться внутри вызываемой функции.

Список argument_list больше не используется и всегда будет равен None. Аргумент сохраняется для обратной совместимости.

user_line(frame)

Вызывается из dispatch_line(), когда либо stop_here(), либо break_here() возвращает True.

user_return(frame, return_value)

Вызывается из dispatch_return(), когда stop_here() возвращает True.

user_exception(frame, exc_info)

Вызывается из dispatch_exception(), когда stop_here() возвращает True.

do_clear(arg)

Укажите, как удалить точку останова, если она является временной.

Этот метод должен быть реализован производными классами.

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

set_step()

Остановитесь после одной строки кода.

set_next(frame)

Остановитесь на следующей строке в заданном фрейме или под ним.

set_return(frame)

Остановка при возврате из заданного кадра.

set_until(frame, lineno=None)

Остановка при достижении строки с lineno больше текущей или при возврате из текущего кадра.

set_trace([frame])

Начать отладку с кадра. Если frame не указан, отладка начинается с кадра вызывающей стороны.

Изменено в версии 3.13: set_trace() войдет в отладчик сразу, а не на следующей выполняемой строке кода.

set_continue()

Останавливайтесь только в точках останова или по завершении работы. Если точек останова нет, установите для функции трассировки системы значение None.

set_quit()

Установите для атрибута quitting значение True. Это повышает значение BdbQuit при следующем вызове одного из методов dispatch_*().

Производные классы и клиенты могут вызывать следующие методы для работы с точками останова. Эти методы возвращают строку, содержащую сообщение об ошибке, если что-то пошло не так, или None, если все в порядке.

set_break(filename, lineno, temporary=False, cond=None, funcname=None)

Установить новую точку останова. Если строка lineno не существует для filename, переданного в качестве аргумента, возвращается сообщение об ошибке. Имя filename должно быть в канонической форме, как описано в методе canonic().

clear_break(filename, lineno)

Удалить точки останова в filename и lineno. Если они не были установлены, верните сообщение об ошибке.

clear_bpbynumber(arg)

Удалите точку останова, которая имеет индекс arg в Breakpoint.bpbynumber. Если arg не является числовым или выходит за пределы диапазона, возвращается сообщение об ошибке.

clear_all_file_breaks(filename)

Удалить все точки останова в filename. Если ни одна из них не была установлена, возвращается сообщение об ошибке.

clear_all_breaks()

Удалить все существующие точки останова. Если ни одна из них не была установлена, возвращается сообщение об ошибке.

get_bpbynumber(arg)

Возвращает точку останова, указанную заданным числом. Если arg - строка, она будет преобразована в число. Если arg - не числовая строка, если заданная точка останова никогда не существовала или была удалена, то будет вызвана ошибка ValueError.

Added in version 3.2.

get_break(filename, lineno)

Возвращает True, если существует точка останова для lineno в filename.

get_breaks(filename, lineno)

Возвращает все точки останова для lineno в filename, или пустой список, если ни одна из них не установлена.

get_file_breaks(filename)

Возвращает все точки останова в filename, или пустой список, если ни одна из них не установлена.

get_all_breaks()

Возвращает все установленные точки останова.

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

get_stack(f, t)

Возвращает список (frame, lineno) кортежей в трассировке стека и размер.

Последний вызванный кадр будет последним в списке. Размер - это количество кадров ниже кадра, в котором был вызван отладчик.

format_stack_entry(frame_lineno, lprefix=': ')

Возвращает строку с информацией о записи в стеке, которая представляет собой кортеж (frame, lineno). Возвращаемая строка содержит:

• Каноническое имя файла, содержащего кадр.

• Имя функции или "<lambda>".

• Входные аргументы.

• Возвращаемое значение.

• Строка кода (если она существует).

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

run(cmd, globals=None, locals=None)

Отладка оператора, выполняемого с помощью функции exec(). globals по умолчанию принимает значение __main__.__dict__, locals по умолчанию принимает значение globals.

runeval(expr, globals=None, locals=None)

Отладка выражения, выполняемого с помощью функции eval(). globals и locals имеют то же значение, что и в run().

runctx(cmd, globals, locals)

Для обратной совместимости. Вызывает метод run().

runcall(func, /, *args, **kwds)

Отладка одного вызова функции и возврат ее результата.

Наконец, в модуле определены следующие функции:

bdb.checkfuncname(b, frame)

Верните True, если мы должны прерваться здесь, в зависимости от того, как Breakpoint b было установлено.

Если она была установлена по номеру строки, то проверяется, совпадает ли b.line с номером строки в кадре. Если точка останова была установлена через function name, необходимо проверить, что мы находимся в правильном кадре (правильной функции) и на первой исполняемой строке.

bdb.effective(file, line, frame)

Верните (active breakpoint, delete temporary flag) или (None, None) в качестве точки останова для действия.

Активная точка останова* - это первая запись в bplist для (file, line) (которая должна существовать), которая является enabled, для которой checkfuncname() истинна, и которая не имеет ни ложного condition, ни положительного ignore счета. Флаг *, означающий, что временная точка останова должна быть удалена, является False только в том случае, если cond не может быть оценен (в этом случае счет ignore игнорируется).

Если такой записи нет, то возвращается (None, None).

bdb.set_trace()

Начните отладку с экземпляра Bdb из кадра вызывающей стороны.