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

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

pprint([out])

Вывести всю информацию о точке останова:

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

class bdb.Bdb(skip=None)

Класс Bdb служит базовым классом для отладчиков Python общего назначения.

Этот класс отвечает за детали механизма отслеживания; производный класс должен реализовывать пользовательское взаимодействие. Стандартный класс отладчика (pdb.Pdb) является примером.

Аргумент skip, если указан, должен быть итерируемым объектом с шаблонами имён модулей в стиле glob. Отладчик не будет входить в фреймы, происходящие из модуля, соответствующего одному из этих шаблонов. Определение, происходит ли фрейм из определённого модуля, определяется по __name__ в глобальных переменных фрейма.

Новое в версии 2.7: Аргумент 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=None, funcname=None)

Установить новую точку останова. Если строки 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_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[, locals]])

Отлаживать оператор, выполняемый с помощью оператора exec. globals по умолчанию __main__.__dict__, locals по умолчанию globals.

runeval(expr[, globals[, locals]])

Отлаживать выражение, выполняемое с помощью функции 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 из фрейма вызывающего метода.