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

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

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

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

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

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

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

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

Точки останова индексируются по номеру через список, называемый bpbynumber, и по парам «файл/строка» через 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 указан, он должен быть итерируемым объектом с шаблонами имён модулей в формате глобов. Отладчик не будет входить в фреймы, происходящие из модуля, соответствующего одному из этих шаблонов. Определение того, происходит ли фрейм из определённого модуля, определяется __name__ в глобальных переменных фрейма.

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

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

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

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() для дальнейшего отслеживания в данном контексте.

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

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 из фрейма вызывающего.