Документация Python неофициальный перевод

bdb – фреймворк отладчикаbdb – Debugger framework

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

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

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

exception bdb.BdbQuit

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

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

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

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

Точки останова индексируются по номеру через список с именем bpbynumber и по парам (file, line) через bplist. Первый указывает на один экземпляр класса Breakpoint. Второй указывает на список таких экземпляров, так как на одной строке может быть несколько точек останова.

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

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

deleteMe()

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

enable()

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

disable()

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

bpformat()

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

  • Номер точки останова.

  • Временный статус (del или keep).

  • Позиция файла/строки.

  • Условие останова.

  • Количество пропусков.

  • Количество срабатываний.

Добавлено в версии 3.2.

bpprint(out=None)

Выводит результат bpformat() в файл out или, если он равен None, на стандартный вывод.

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

file

Имя файла Breakpoint.

line

Номер строки Breakpoint в file.

temporary

True, если Breakpoint в (файл, строка) временная.

cond

Условие для вычисления Breakpoint в (файл, строка).

funcname

Имя функции, определяющее, срабатывает ли Breakpoint при входе в функцию.

enabled

True, если Breakpoint включён.

bpbynumber

Числовой индекс для одного экземпляра Breakpoint.

bplist

Словарь экземпляров Breakpoint, проиндексированных кортежами (file, line).

ignore

Количество раз, которое нужно игнорировать Breakpoint.

hits

Счётчик количества срабатываний Breakpoint.

class bdb.Bdb(skip=None, backend='settrace')

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

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

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

Аргумент backend указывает используемый внутренний механизм для Bdb. Он может быть либо 'settrace', либо 'monitoring'. 'settrace' использует sys.settrace(), который обеспечивает наилучшую обратную совместимость. Внутренний механизм 'monitoring' использует новый sys.monitoring, появившийся в Python 3.12, который может быть гораздо эффективнее, поскольку он может отключать неиспользуемые события. Мы стараемся сохранить точные интерфейсы для обоих внутренних механизмов, но есть некоторые различия. Разработчикам отладчика рекомендуется использовать внутренний механизм 'monitoring' для достижения лучшей производительности.

Изменено в версии 3.1: Добавлен параметр skip.

Изменено в версии 3.14: Добавлен параметр backend.

Следующие методы Bdb обычно не требуют переопределения.

canonic(filename)

Возвращает каноническую форму filename.

Для реальных имён файлов каноническая форма зависит от операционной системы, case-normalized absolute path. filename с угловыми скобками, например "<stdin>", сгенерированное в интерактивном режиме, возвращается без изменений.

start_trace(self)

Запускает трассировку. Для внутреннего механизма 'settrace' этот метод эквивалентен sys.settrace(self.trace_dispatch)

Добавлено в версии 3.14.

stop_trace(self)

Останавливает трассировку. Для бэкенда 'settrace' этот метод эквивалентен sys.settrace(None)

Добавлено в версии 3.14.

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, если установлен флаг quitting (который можно установить из user_line()). Возвратить ссылку на метод trace_dispatch() для дальнейшей трассировки в этой области видимости.

dispatch_call(frame, arg)

Если отладчик должен остановиться на этом вызове функции, вызвать метод user_call() (который следует переопределять в подклассах). Возбудить исключение BdbQuit, если установлен флаг quitting (который можно установить из user_call()). Возвратить ссылку на метод trace_dispatch() для дальнейшей трассировки в этой области видимости.

dispatch_return(frame, arg)

Если отладчик должен остановиться на этом возврате из функции, вызвать метод user_return() (который следует переопределять в подклассах). Возбудить исключение BdbQuit, если установлен флаг quitting (который можно установить из user_return()). Возвратить ссылку на метод trace_dispatch() для дальнейшей трассировки в этой области видимости.

dispatch_exception(frame, arg)

Если отладчик должен остановиться на этом исключении, вызывается метод user_exception() (который следует переопределять в подклассах). Возбудить исключение BdbQuit, если установлен флаг quitting (который можно установить из user_exception()). Возвратить ссылку на метод trace_dispatch() для дальнейшей трассировки в этой области видимости.

Обычно производные классы не переопределяют следующие методы, но могут, если хотят переопределить определение остановки и точек останова.

is_skipped_module(module_name)

Возвращает True, если module_name соответствует какому-либо шаблону пропуска.

stop_here(frame)

Возвращает True, если frame находится ниже начального фрейма в стеке.

break_here(frame)

Возвращает True, если для этой строки есть действующая точка останова.

Проверяет, существует ли точка останова на строку или функцию и активна ли она. Удаляет временные точки останова на основе информации из effective().

break_anywhere(frame)

Возвращает True, если для имени файла frame существует какая-либо точка останова.

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

user_call(frame, argument_list)

Вызывается из dispatch_call(), если точка останова может сработать внутри вызываемой функции.

argument_list больше не используется и всегда будет None. Аргумент сохранён для обратной совместимости.

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, lineno=None)

Остановиться, когда будет достигнута строка с lineno больше текущей, или при возврате из текущего фрейма.

set_trace([frame])

Начать отладку с frame. Если frame не указан, отладка начинается с фрейма вызывающего кода.

Изменено в версии 3.13: set_trace() теперь войдёт в отладчик немедленно, а не на следующей исполняемой строке кода.

set_continue()

Останавливаться только в точках останова или при завершении. Если точек останова нет, устанавливает системную трассировочную функцию в None.

set_quit()

Устанавливает атрибут quitting в True. Это вызывает BdbQuit при следующем вызове одного из методов dispatch_*().

Производные классы и клиенты могут вызывать следующие методы для управления точками останова. Эти методы возвращают строку с сообщением об ошибке, если что-то пошло не так, или None, если всё в порядке.

set_break(filename, lineno, temporary=False, 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_bpbynumber(arg)

Возвращает точку останова, заданную указанным номером. Если arg – строка, она преобразуется в число. Если arg – нечисловая строка, если указанная точка останова никогда не существовала или была удалена, возбуждается ValueError.

Добавлено в версии 3.2.

get_break(filename, lineno)

Возвращает True, если для lineno в filename существует точка останова.

get_breaks(filename, lineno)

Возвращает все точки останова для lineno в filename, или пустой список, если ни одной не установлено.

get_file_breaks(filename)

Возвращает все точки останова в filename, или пустой список, если ни одной не установлено.

get_all_breaks()

Возвращает все установленные точки останова.

Производные классы и клиенты могут вызывать следующие методы, чтобы отключать и перезапускать события для повышения производительности. Эти методы работают только при использовании внутреннего механизма 'monitoring'.

disable_current_event()

Отключает текущее событие до тех пор, пока restart_events() не будет вызван снова. Это полезно, когда отладчику не интересна текущая строка.

Добавлено в версии 3.14.

restart_events()

Перезапускает все отключённые события. Эта функция автоматически вызывается в методах dispatch_* после вызова методов user_*. Если методы dispatch_* не переопределены, отключённые события будут перезапускаться после каждого взаимодействия с пользователем.

Добавлено в версии 3.14.

Производные классы и клиенты могут вызывать следующие методы для получения структуры данных, представляющей стек вызовов.

get_stack(f, t)

Возвращает список кортежей (frame, lineno) в стеке вызовов, а также размер.

Самый последний вызванный фрейм находится в конце списка. Размер – это количество фреймов ниже фрейма, в котором был вызван отладчик.

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)

Возвращает True, если здесь нужно остановиться, в зависимости от того, как была установлена Breakpoint b.

Если она была установлена по номеру строки, проверяется, совпадает ли b.line с номером в фрейме. Если точка останова была установлена через function name, необходимо проверить, находимся ли мы в правильном фрейме (правильной функции) и находимся ли на первой исполняемой строке.

bdb.effective(file, line, frame)

Возвращает (active breakpoint, delete temporary flag) или (None, None) как точку останова, с которой нужно работать.

Активная точка останова – это первая запись в bplist для (file, line) (которая должна существовать), которая является enabled, для которой checkfuncname() истинно, и у которой нет ни ложного condition, ни положительного ignore счётчика. Флаг, означающий, что временная точка останова должна быть удалена, равен False только тогда, когда cond невозможно вычислить (в этом случае ignore счётчик игнорируется).

Если такой записи не существует, возвращается (None, None).

bdb.set_trace()

Начинает отладку с экземпляром Bdb из фрейма вызывающего кода.