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

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 из кадра вызывающей функции.