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

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

Номер точки останова.
Временный статус (del или keep).
Позиция в файле и строке.
Условие остановки.
Количество игнорирований.
Количество срабатываний.

Добавлено в версии 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 не указан, отладка начинается с кадра вызывающего кода.

Изменено в версии 3.13: set_trace() немедленно запускает отладчик, а не ждёт следующей выполняемой строки кода.

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() возвращает true, а условие condition не ложно и счётчик ignore не положителен. Флаг, указывающий на необходимость удалить временную точку останова, принимает значение False только в том случае, если условие cond невозможно вычислить (в этом случае счётчик ignore игнорируется).

Если такой записи нет, возвращается (None, None).

bdb.set_trace(): Начинает отладку с помощью экземпляра Bdb, начиная с кадра вызывающего кода.