27.1. bdb – Фреймворк отладчика¶bdb – Debugger framework

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

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

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

exception bdb.BdbQuit¶

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

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

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

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

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

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

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

deleteMe()¶

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

enable()¶

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

disable()¶

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

bpformat()¶

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

• Номер точки останова.
• Является ли она временной.
• Её позиция (файл, строка).
• Условие, вызывающее останов.
• Должна ли игнорироваться следующие N раз.
• Счётчик срабатываний точки останова.

Новое в версии 3.2.

bpprint(out=None)¶

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

class bdb.Bdb(skip=None)¶

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

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

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

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

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

canonic(filename)¶

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

reset()¶

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

trace_dispatch(frame, event, arg)¶

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

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

• "line": Будет выполнена новая строка кода.
• "call": Функция будет вызвана, или будет вход в другой блок кода.
• "return": Функция или другой блок кода готовится выполнить возврат.
• "исключение": Произошло исключение.
• "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() для дальнейшей трассировки в этой области.

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

stop_here(frame)¶

Этот метод проверяет, находится ли frame где-то ниже botframe в стеке вызовов. botframe – это фрейм, в котором началась отладка.

break_here(frame)¶

Этот метод проверяет, есть ли точка останова в файле и строке, соответствующих frame, или хотя бы в текущей функции. Если точка останова временная, этот метод удаляет её.

break_anywhere(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)¶

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

set_trace([frame])¶

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

set_continue()¶

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

set_quit()¶

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

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

set_break(filename, lineno, temporary=0, cond, funcname)¶

Устанавливает новую точку останова. Если строка 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)¶

Проверяет, существует ли точка останова для 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)¶

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

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

bdb.effective(file, line, frame)¶

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

bdb.set_trace()¶

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