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

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

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

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

exception bdb.BdbQuit

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

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

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

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

Точки останова индексируются по номеру через список, называемый bpbynumber, и по парам «файл/строка» через bplist. Первый указывает на единственный экземпляр класса Breakpoint. Последний указывает на список таких экземпляров, так как может быть более одной точки останова на строке.

При создании точки останова связанный с ней файл должен быть в канонической форме. Если определен funcname, попадание в точку останова будет учитываться при выполнении первой строки этой функции. Условная точка останова всегда учитывается как попадание.

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

deleteMe()

Удалить точку останова из списка, связанного с файлом/строкой. Если это последняя точка останова в этой позиции, то удаляется и запись для файла/строки.

enable()

Пометить точку останова как включённую.

disable()

Пометить точку останова как выключенную.

bpformat()

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

• Номер точки останова.
• Является ли она временной или нет.
• Её позиция в файле и строке.
• Условие, которое вызывает останов.
• Число раз, когда она должна быть проигнорирована.
• Счётчик попаданий в точку останова.

Новая в версии 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 из фрейма вызывающей функции.