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).
Позиция файла/строки.
Условие останова.
Количество раз для игнорирования.
Количество раз, когда точка останова была достигнута.

Добавлена в версии 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)

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

Стандартная реализация определяет способ обработки фрейма в зависимости от типа события (переданного как строка), которое будет выполнено. 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, если установлен флаг 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 если module_name соответствует любому шаблону пропуска.

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

break_here(frame)

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

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

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

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

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]): Начать отладку с кадра. Если кадр не указан, отладка начинается с кадра вызывающей функции.

Изменено в версии 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.

Добавлена в версии 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)

Возвращает список кортежей (кадр, номер строки) в стеке вызовов и его размер.

Наиболее недавно вызванный кадр находится в конце списка. Размер — количество кадров ниже кадра, в котором был вызван отладчик.

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() истинно и у которого нет ложного condition ни положительного ignore счётчика. Флаг, означающий, что временная точка останова должна быть удалена, равен False только когда cond не может быть вычислен (в этом случае счётчик ignore игнорируется).

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

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