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

Исходный код: 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 из кадра вызывающей функции.