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

Исходный код: Lib/bdb.py

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

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

exception bdb.BdbQuit: Исключение, генерируемое классом Bdb для выхода из отладчика.

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

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

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

Точки останова индексируются по номеру в списке, называемом bpbynumber, и по парам «файл/строка» через bplist. Первый указывает на единственный экземпляр класса Breakpoint. Последний указывает на список таких экземпляров, так как может быть более одной точки останова на строке.

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

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

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

enable(): Отметить точку останова как активную.

disable(): Отметить точку останова как отключенную.

bpformat()

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

Номер точки останова.
Временный статус (удалить или сохранить).
Позиция файла/строки.
Условие останова.
Количество игнорирований.
Количество срабатываний.

Введено в версии 3.2.

bpprint(out=None): Выводит результат bpformat() в файл out или, если он None, в стандартный вывод.

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

file: Имя файла точки останова.

line: Номер строки точки останова в file.

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

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

funcname: Имя функции, определяющее, была ли достигнута точка останова при входе в функцию.

enabled: True, если точка останова активна.

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

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

ignore: Количество игнорирований точки останова.

hits: Количество срабатываний точки останова.

class bdb.Bdb(skip=None)

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

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

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

Нововведение в версии 3.1: Аргумент skip.

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

canonic(filename)

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

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

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

trace_dispatch(frame, event, arg)

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

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

"line": Будет выполнена новая строка кода.
"call": Функция должна быть вызвана, или другой блок кода должен быть введен.
"return": Функция или другой блок кода должны вернуть значение.
"exception": Произошло исключение.
"c_call": Функция C должна быть вызвана.
"c_return": Функция C вернула значение.
"c_exception": Функция C вызвала исключение.

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

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

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

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

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

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

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

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

is_skipped_line(module_name): Возвращает True, если module_name соответствует любому шаблону пропуска.

stop_here(frame): Возвращает True, если frame находится ниже начального фрейма в стеке.

break_here(frame)

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

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

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

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

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

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. Если frame не указан, отладка начинается с фрейма вызывающего.

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.

Введено в версии 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>".
Аргументы ввода.
Значение возврата.
Строка кода (если она существует).

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

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 тому, что в frame. Если контрольная точка была установлена по function name, мы должны проверить, находимся ли мы в правильном frame (правильной функции) и находимся ли мы на первой исполняемой строке.

bdb.effective(file, line, frame)

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

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

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

bdb.set_trace(): Начать отладку с экземпляром Bdb из кадра вызывающего.