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 в позиции (файл, строка) является временной.

cond: Условие для проверки Breakpoint в позиции (файл, строка).

funcname: Имя функции, определяющее, будет ли срабатывать Breakpoint при входе в функцию.

enabled: True, если Breakpoint включена.

bpbynumber: Числовой индекс отдельного экземпляра Breakpoint.

bplist: Словарь экземпляров Breakpoint, индексируемых кортежами (file, line).

ignore: Количество раз, которое следует игнорировать Breakpoint.

hits: Число попаданий в Breakpoint.

class bdb.Bdb(skip=None, backend='settrace')

Класс Bdb служит базовым классом универсального отладчика Python.

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

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

Аргумент backend задаёт используемую серверную часть для Bdb. Его значение может быть 'settrace' или 'monitoring'. 'settrace' использует sys.settrace(), обеспечивающую наилучшую обратную совместимость. Серверная часть 'monitoring' использует новый механизм sys.monitoring, появившийся в Python 3.12; он может работать значительно эффективнее, поскольку позволяет отключать неиспользуемые события. Мы стараемся сохранять одинаковые интерфейсы для обеих серверных частей, но между ними есть некоторые различия. Разработчикам отладчиков рекомендуется использовать серверную часть 'monitoring' для повышения производительности.

Изменено в версии 3.1: Добавлен параметр skip.

Изменено в версии 3.14: Добавлен параметр backend.

Обычно методы Bdb не требуют переопределения.

canonic(filename)

Вернуть каноническую форму filename.

Для реальных имён файлов каноническая форма — это абсолютный путь, приведённый к стандартному для операционной системы регистру с помощью case-normalized и absolute path. Имя файла filename в угловых скобках, например "<stdin>", созданное в интерактивном режиме, возвращается без изменений.

start_trace(self): Начать трассировку. Для серверной части 'settrace' этот метод эквивалентен sys.settrace(self.trace_dispatch)

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

stop_trace(self): Остановить трассировку. Для серверной части 'settrace' этот метод эквивалентен sys.settrace(None)

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

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

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

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

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

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

is_skipped_module(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(): Вернуть все установленные точки останова.

Производные классы и клиенты могут вызывать следующие методы для отключения и повторного запуска событий с целью повышения производительности. Эти методы работают только при использовании серверной части 'monitoring'.

disable_current_event(): Отключить текущее событие до следующего вызова restart_events(). Это полезно, когда отладчику не интересна текущая строка.

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

restart_events(): Повторно запустить все отключённые события. Эта функция автоматически вызывается в методах dispatch_* после вызова методов user_*. Если методы dispatch_* не переопределены, отключённые события будут повторно запускаться после каждого взаимодействия с пользователем.

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

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

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.