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()

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

• Номер точки останова.
• Является ли она временной или нет.
• Позиция файла и строки.
• Условие, вызывающее остановку.
• Необходимо ли пропустить 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 из фрейма вызывающей функции.