> **Источник:** https://python-all.ru/3.0/library/bdb.html
>
> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.

---

# `bdb` – Каркас отладчика

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

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

#### `[bdb.BdbQuit]exception bdb.BdbQuit`

Исключение, вызываемое классом

[`Bdb`](https://python-all.ru/3.0/library/bdb.html#bdb.Bdb)

для выхода из отладчика.

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

#### `[bdb.Breakpoint]class bdb.Breakpoint(self, file, line[, temporary=0[, cond=None[, funcname=None]]])`

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

Точки останова индексируются по номеру через список `bpbynumber` и по парам `(file, line)` через `bplist`. Первый ссылается на единственный экземпляр класса [`Breakpoint`](https://python-all.ru/3.0/library/bdb.html#bdb.Breakpoint). Второй ссылается на список таких экземпляров, поскольку на одной строке может быть более одной точки останова.

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

Экземпляры [`Breakpoint`](https://python-all.ru/3.0/library/bdb.html#bdb.Breakpoint) имеют следующие методы:

#### `[bdb.Breakpoint.deleteMe]deleteMe()`

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

#### `[bdb.Breakpoint.enable]enable()`

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

#### `[bdb.Breakpoint.disable]disable()`

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

#### `[bdb.Breakpoint.pprint]pprint([out])`

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

- Номер точки останова.
- Является ли она временной.
- Её позиция (файл, строка).
- Условие, вызывающее останов.
- Должна ли игнорироваться следующие N раз.
- Счётчик срабатываний точки останова.

#### `[bdb.Bdb]class bdb.Bdb`

[`Bdb`](https://python-all.ru/3.0/library/bdb.html#bdb.Bdb) выступает в роли универсального базового класса отладчика Python.

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

Следующие методы [`Bdb`](https://python-all.ru/3.0/library/bdb.html#bdb.Bdb) обычно не нужно переопределять.

#### `[bdb.Bdb.canonic]canonic(filename)`

Вспомогательный метод для получения имени файла в канонической форме, то есть в виде абсолютного пути с нормализованным регистром (на файловых системах без учёта регистра), из которого удалены обрамляющие угловые скобки.

#### `[bdb.Bdb.reset]reset()`

Устанавливает атрибуты

`botframe`

,

`stopframe`

,

`returnframe`

и

`quitting`

со значениями, готовыми к началу отладки.

#### `[bdb.Bdb.trace_dispatch]trace_dispatch(frame, event, arg)`

Эта функция устанавливается как трассирующая функция для отлаживаемых фреймов. Её возвращаемое значение – новая трассирующая функция (в большинстве случаев она же).

Реализация по умолчанию определяет, как диспетчеризовать фрейм, в зависимости от типа события (передаётся строкой), которое должно быть выполнено. *event* может быть одним из следующих:

- `"line"`: Будет выполнена новая строка кода.
- `"call"`: Функция будет вызвана, или будет вход в другой блок кода.
- `"return"`: Функция или другой блок кода готовится выполнить возврат.
- `"исключение"`: Произошло исключение.
- `"c_call"`: Будет вызвана C-функция.
- `"c_return"`: C-функция вернулась.
- `"c_exception"`: функция на C вызвала исключение.

Для событий Python вызываются специализированные функции (см. ниже). Для событий C никаких действий не выполняется.

Параметр *arg* зависит от предыдущего события.

Дополнительную информацию о функции трассировки см. в документации к [`sys.settrace()`](https://python-all.ru/3.0/library/sys.html#sys.settrace). Для получения дополнительных сведений об объектах кода и фреймов обращайтесь к [*Стандартной иерархии типов*](https://python-all.ru/3.0/reference/datamodel.html#types).

#### `[bdb.Bdb.dispatch_line]dispatch_line(frame)`

Если отладчик должен остановиться на текущей строке, вызывается метод

[`user_line()`](https://python-all.ru/3.0/library/bdb.html#bdb.Bdb.user_line)

(который должен быть переопределён в подклассах). Возбуждается исключение

[`BdbQuit`](https://python-all.ru/3.0/library/bdb.html#bdb.BdbQuit)

, если установлен флаг

`Bdb.quitting`

(который может быть установлен из

[`user_line()`](https://python-all.ru/3.0/library/bdb.html#bdb.Bdb.user_line)

). Возвращается ссылка на метод

[`trace_dispatch()`](https://python-all.ru/3.0/library/bdb.html#bdb.Bdb.trace_dispatch)

для дальнейшей трассировки в этой области.

#### `[bdb.Bdb.dispatch_call]dispatch_call(frame, arg)`

Если отладчик должен остановиться на этом вызове функции, вызывается метод

[`user_call()`](https://python-all.ru/3.0/library/bdb.html#bdb.Bdb.user_call)

(который должен быть переопределён в подклассах). Возбуждается исключение

[`BdbQuit`](https://python-all.ru/3.0/library/bdb.html#bdb.BdbQuit)

, если установлен флаг

`Bdb.quitting`

(который может быть установлен из

[`user_call()`](https://python-all.ru/3.0/library/bdb.html#bdb.Bdb.user_call)

). Возвращается ссылка на метод

[`trace_dispatch()`](https://python-all.ru/3.0/library/bdb.html#bdb.Bdb.trace_dispatch)

для дальнейшей трассировки в этой области.

#### `[bdb.Bdb.dispatch_return]dispatch_return(frame, arg)`

Если отладчик должен остановиться на этом возврате из функции, вызывается метод

[`user_return()`](https://python-all.ru/3.0/library/bdb.html#bdb.Bdb.user_return)

(который должен быть переопределён в подклассах). Возбуждается исключение

[`BdbQuit`](https://python-all.ru/3.0/library/bdb.html#bdb.BdbQuit)

, если установлен флаг

`Bdb.quitting`

(который может быть установлен из

[`user_return()`](https://python-all.ru/3.0/library/bdb.html#bdb.Bdb.user_return)

). Возвращается ссылка на метод

[`trace_dispatch()`](https://python-all.ru/3.0/library/bdb.html#bdb.Bdb.trace_dispatch)

для дальнейшей трассировки в этой области.

#### `[bdb.Bdb.dispatch_exception]dispatch_exception(frame, arg)`

Если отладчик должен остановиться на этом исключении, вызывается метод

[`user_exception()`](https://python-all.ru/3.0/library/bdb.html#bdb.Bdb.user_exception)

(который должен быть переопределён в подклассах). Возбуждается исключение

[`BdbQuit`](https://python-all.ru/3.0/library/bdb.html#bdb.BdbQuit)

, если установлен флаг

`Bdb.quitting`

(который может быть установлен из

[`user_exception()`](https://python-all.ru/3.0/library/bdb.html#bdb.Bdb.user_exception)

). Возвращается ссылка на метод

[`trace_dispatch()`](https://python-all.ru/3.0/library/bdb.html#bdb.Bdb.trace_dispatch)

для дальнейшей трассировки в этой области.

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

#### `[bdb.Bdb.stop_here]stop_here(frame)`

Этот метод проверяет, находится ли

*frame*

где-то ниже

`botframe`

в стеке вызовов.

`botframe`

– это фрейм, в котором началась отладка.

#### `[bdb.Bdb.break_here]break_here(frame)`

Этот метод проверяет, есть ли точка останова в файле и строке, соответствующих

*frame*

, или хотя бы в текущей функции. Если точка останова временная, этот метод удаляет её.

#### `[bdb.Bdb.break_anywhere]break_anywhere(frame)`

Этот метод проверяет, есть ли точка останова в имени файла текущего кадра.

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

#### `[bdb.Bdb.user_call]user_call(frame, argument_list)`

Этот метод вызывается из

[`dispatch_call()`](https://python-all.ru/3.0/library/bdb.html#bdb.Bdb.dispatch_call)

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

#### `[bdb.Bdb.user_line]user_line(frame)`

Этот метод вызывается из

[`dispatch_line()`](https://python-all.ru/3.0/library/bdb.html#bdb.Bdb.dispatch_line)

, когда

[`stop_here()`](https://python-all.ru/3.0/library/bdb.html#bdb.Bdb.stop_here)

или

[`break_here()`](https://python-all.ru/3.0/library/bdb.html#bdb.Bdb.break_here)

возвращает True.

#### `[bdb.Bdb.user_return]user_return(frame, return_value)`

Этот метод вызывается из

[`dispatch_return()`](https://python-all.ru/3.0/library/bdb.html#bdb.Bdb.dispatch_return)

, когда

[`stop_here()`](https://python-all.ru/3.0/library/bdb.html#bdb.Bdb.stop_here)

возвращает True.

#### `[bdb.Bdb.user_exception]user_exception(frame, exc_info)`

Этот метод вызывается из

[`dispatch_exception()`](https://python-all.ru/3.0/library/bdb.html#bdb.Bdb.dispatch_exception)

, когда

[`stop_here()`](https://python-all.ru/3.0/library/bdb.html#bdb.Bdb.stop_here)

возвращает True.

#### `[bdb.Bdb.do_clear]do_clear(arg)`

Обрабатывает, как должна быть удалена точка останова, если она временная.

Этот метод должен быть реализован в производных классах.

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

#### `[bdb.Bdb.set_step]set_step()`

Остановиться после одной строки кода.

#### `[bdb.Bdb.set_next]set_next(frame)`

Остановиться на следующей строке внутри или ниже заданного фрейма.

#### `[bdb.Bdb.set_return]set_return(frame)`

Остановиться при возврате из заданного фрейма.

#### `[bdb.Bdb.set_until]set_until(frame)`

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

#### `[bdb.Bdb.set_trace]set_trace([frame])`

Начать отладку с

*frame*

. Если

*frame*

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

#### `[bdb.Bdb.set_continue]set_continue()`

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

#### `[bdb.Bdb.set_quit]set_quit()`

Устанавливает атрибут

`quitting`

в True. При\\nследующем вызове одного из методов

`dispatch_*()`

это вызывает

[`BdbQuit`](https://python-all.ru/3.0/library/bdb.html#bdb.BdbQuit)

.

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

#### `[bdb.Bdb.set_break]set_break(filename, lineno[, temporary=0[, cond[, funcname]]])`

Устанавливает новую точку останова. Если строка

*lineno*

не существует для

*filename*

, переданного в качестве аргумента, возвращает сообщение об ошибке.

*filename*

должен быть в канонической форме, как описано в методе

[`canonic()`](https://python-all.ru/3.0/library/bdb.html#bdb.Bdb.canonic)

.

#### `[bdb.Bdb.clear_break]clear_break(filename, lineno)`

Удаляет точки останова в

*filename*

и

*lineno*

. Если ни одной не было установлено, возвращается сообщение об ошибке.

#### `[bdb.Bdb.clear_bpbynumber]clear_bpbynumber(arg)`

Удаляет точку останова с индексом

*arg*

из

`Breakpoint.bpbynumber`

. Если

*arg*

не является числом или выходит за пределы диапазона, возвращает сообщение об ошибке.

#### `[bdb.Bdb.clear_all_file_breaks]clear_all_file_breaks(filename)`

Удаляет все точки останова в

*filename*

. Если ни одной не было установлено, возвращается сообщение об ошибке.

#### `[bdb.Bdb.clear_all_breaks]clear_all_breaks()`

Удаляет все существующие точки останова.

#### `[bdb.Bdb.get_break]get_break(filename, lineno)`

Проверяет, существует ли точка останова для

*lineno*

в

*filename*

.

#### `[bdb.Bdb.get_breaks]get_breaks(filename, lineno)`

Возвращает все точки останова для

*lineno*

в

*filename*

, или пустой список, если ни одной не установлено.

#### `[bdb.Bdb.get_file_breaks]get_file_breaks(filename)`

Возвращает все точки останова в

*filename*

, или пустой список, если ни одной не установлено.

#### `[bdb.Bdb.get_all_breaks]get_all_breaks()`

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

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

#### `[bdb.Bdb.get_stack]get_stack(f, t)`

Возвращает список записей для фрейма, всех вышележащих (вызывающих) и нижележащих фреймов, а также размер вышележащей части.

#### `[bdb.Bdb.format_stack_entry]format_stack_entry(frame_lineno[, lprefix=': '])`

Возвращает строку с информацией о записи стека, идентифицируемой кортежем `(frame, lineno)`:

- Каноническая форма имени файла, содержащего фрейм.
- Имя функции или `"<lambda>"`.
- Входные аргументы.
- Возвращаемое значение.
- Строка кода (если она существует).

Следующие два метода могут вызываться клиентами для отладки [*оператора*](https://python-all.ru/3.0/glossary.html#term-statement), заданного строкой.

#### `[bdb.Bdb.run]run(cmd[, globals[, locals]])`

Отлаживает инструкцию, выполняемую через функцию

[`exec()`](https://python-all.ru/3.0/library/functions.html#exec)

.

*globals*

по умолчанию равен

`__main__.__dict__`

, а

*locals*

по умолчанию равен

*globals*

.

#### `[bdb.Bdb.runeval]runeval(expr[, globals[, locals]])`

Отлаживает выражение, выполняемое через функцию

[`eval()`](https://python-all.ru/3.0/library/functions.html#eval)

.

*globals*

и

*locals*

имеют тот же смысл, что и в

[`run()`](https://python-all.ru/3.0/library/bdb.html#bdb.Bdb.run)

.

#### `[bdb.Bdb.runctx]runctx(cmd, globals, locals)`

Для обратной совместимости. Вызывает метод

[`run()`](https://python-all.ru/3.0/library/bdb.html#bdb.Bdb.run)

.

#### `[bdb.Bdb.runcall]runcall(func, *args, **kwds)`

Отлаживает одиночный вызов функции и возвращает её результат.

Наконец, модуль определяет следующие функции:

#### `[bdb.checkfuncname]bdb.checkfuncname(b, frame)`

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

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

#### `[bdb.effective]bdb.effective(file, line, frame)`

Определяет, есть ли действующая (активная) точка останова на этой строке кода. Возвращает номер точки останова или 0, если её нет.

Вызывается только если известно, что в этом месте есть точка останова. Возвращает сработавшую точку останова и флаг, указывающий, можно ли удалить временную точку останова.

#### `[bdb.set_trace]bdb.set_trace()`

Запускает отладку с экземпляром

[`Bdb`](https://python-all.ru/3.0/library/bdb.html#bdb.Bdb)

из фрейма вызывающего кода.