bdb — Фреймворк отладчика


Модуль 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() в выходной файл или, если это 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 из фрейма вызывающего объекта.