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

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

Номер точки останова.
Статус временности (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, если установлен флаг 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): Останов, когда достигнута строка с номером строки, большим текущей, или при возврате из текущего фрейма.

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)

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

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

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