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 из фрейма вызывающего.