27.1. bdb – Каркас отладчика¶bdb – Debugger framework

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

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

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

exception bdb.BdbQuit¶

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

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

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

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

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