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

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

Номер точки останова.
Статус временной точки останова (удалить или оставить).
Позиция в файле и строке.
Условие останова.
Число пропусков.
Число попаданий.

Добавлено в версии 3.2.

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

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

file: Имя файла для Breakpoint.

line: Номер строки для Breakpoint в файле file.

temporary: True, если точка останова Breakpoint в позиции (file, line) является временной.

cond: Условие для проверки точки останова Breakpoint в позиции (file, line).

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. Значение filename с угловыми скобками, например "<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() (который следует переопределить в подклассах). Если установлен флаг quitting (его можно установить из user_line()), возбуждает исключение BdbQuit. Возвращает ссылку на метод trace_dispatch() для дальнейшей трассировки в этой области видимости.

dispatch_call(frame, arg): Если отладчик должен остановиться при этом вызове функции, вызывает метод user_call() (который следует переопределить в подклассах). Если установлен флаг quitting (его можно установить из user_call()), возбуждает исключение BdbQuit. Возвращает ссылку на метод trace_dispatch() для дальнейшей трассировки в этой области видимости.

dispatch_return(frame, arg): Если отладчик должен остановиться при возврате из этой функции, вызывает метод user_return() (который следует переопределить в подклассах). Если установлен флаг quitting (его можно установить из user_return()), возбуждает исключение BdbQuit. Возвращает ссылку на метод trace_dispatch() для дальнейшей трассировки в этой области видимости.

dispatch_exception(frame, arg): Если отладчик должен остановиться при этом исключении, вызывает метод user_exception() (который следует переопределить в подклассах). Если установлен флаг quitting (его можно установить из user_exception()), возбуждает исключение BdbQuit. Возвращает ссылку на метод 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]): Начинает отладку с кадра frame. Если frame не указан, отладка начинается с кадра вызывающей стороны.

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

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

Производные классы и клиенты могут вызывать следующие методы для управления точками останова. Эти методы возвращают строку с сообщением об ошибке, если что-то пошло не так, или 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, если в файле filename на строке lineno есть точка останова.

get_breaks(filename, lineno): Возвращает все точки останова в файле filename на строке lineno или пустой список, если таких точек нет.

get_file_breaks(filename): Возвращает все точки останова в файле filename или пустой список, если таких точек нет.

get_all_breaks(): Возвращает все установленные точки останова.

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

get_stack(f, t)

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

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

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 из кадра вызывающей стороны.