pdb — Дебаггер Python

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

Модуль pdb определяет интерактивный отладчик исходного кода для программ Python. Он поддерживает установку (условных) точек останова и пошаговое выполнение по строкам исходного кода, инспекцию кадров стека, вывод списка исходного кода и вычисление произвольного кода Python в контексте любого кадра стека. Он также поддерживает пост-мортальную отладку и может вызываться под управлением программы.

Дебаггер расширяемый — он фактически определён как класс Pdb. В настоящее время это не документировано, но легко понять, прочитав исходный код. Интерфейс расширения использует модули bdb и cmd.

См. также

Module faulthandler: Используется для явного вывода трассировок Python при ошибках, по истечении времени ожидания или при сигнале пользователя.
Module traceback: Стандартный интерфейс для извлечения, форматирования и вывода трассировок стека программ Python.

Типичное использование для входа в дебаггер — вставка:

import pdb; pdb.set_trace()

Или:

breakpoint()

в место, где вы хотите войти в дебаггер, а затем запустить программу. Вы можете выполнить пошаговый проход кода, следуя этому оператору, и продолжить выполнение без дебаггера, используя команду continue.

Новое в версии 3.7: Встроенная функция breakpoint(), когда вызывается со значениями по умолчанию, может быть использована вместо import pdb; pdb.set_trace().

def double(x):
   breakpoint()
   return x * 2
val = 3
print(f"{val} * 2 is {double(val)}")

Подсказка дебаггера — (Pdb), что указывает на то, что вы находитесь в режиме отладки:

> ...(3)double()
-> return x * 2
(Pdb) p x
3
(Pdb) continue
3 * 2 is 6

Изменено в версии 3.3: Доступна автодополнение с помощью модуля readline для команд и аргументов команд, например, текущие глобальные и локальные имена предлагаются в качестве аргументов команды p.

Вы также можете вызвать pdb из командной строки для отладки других скриптов. Например:

python -m pdb myscript.py

Когда pdb вызывается как модуль, он автоматически входит в режим пост-мортальной отладки, если программа, которую вы отлаживаете, завершается аномально. После пост-мортальной отладки (или после нормального завершения программы) pdb перезапустит программу. Автоматическое перезапуск сохраняет состояние pdb (например, точки останова) и в большинстве случаев более полезно, чем выход из дебаггера при завершении программы.

Новое в версии 3.2: Введён параметр -c для выполнения команд так, как будто они указаны в файле .pdbrc, см. Команды дебаггера.

Новое в версии 3.7: Введён параметр -m для выполнения модулей аналогично тому, как это делает python -m. Как и со скриптом, дебаггер приостановит выполнение незадолго до первой строки модуля.

Типичное использование для выполнения оператора под управлением дебаггера:

>>> import pdb
>>> def f(x):
...     print(1 / x)
>>> pdb.run("f(2)")
> <string>(1)<module>()
(Pdb) continue
0.5
>>>

Типичное использование для проверки работы аварийно завершившейся программы:

>>> import pdb
>>> def f(x):
...     print(1 / x)
...
>>> f(0)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 2, in f
ZeroDivisionError: division by zero
>>> pdb.pm()
> <stdin>(2)f()
(Pdb) p x
0
(Pdb)

Модуль определяет следующие функции; каждая из них входит в дебаггер немного по-разному:

pdb.run(statement, globals=None, locals=None): Выполнить оператор (указанный как строка или объект кода) под управлением дебаггера. Подсказка дебаггера появляется до выполнения любого кода; вы можете установить точки останова и ввести continue, или вы можете выполнить оператор пошагово с помощью step или next (все эти команды описаны ниже). Необязательные аргументы globals и locals задают среду, в которой выполняется код; по умолчанию используется словарь модуля __main__. (См. объяснение встроенных функций exec() или eval().)

pdb.runeval(expression, globals=None, locals=None): Вычислить выражение (указанное как строка или объект кода) под управлением дебаггера. Когда runeval() возвращает значение, оно возвращает значение выражения. В противном случае эта функция аналогична run().

pdb.runcall(function, *args, **kwds): Вызвать функцию (объект функции или метода, а не строку) с заданными аргументами. Когда runcall() возвращает значение, оно возвращает значение, возвращённое функцией. Подсказка дебаггера появляется сразу после входа в функцию.

pdb.set_trace(*, header=None): Включить дебаггер в кадре вызова стека. Это полезно для вставки точки останова в заданной точке программы, даже если код не отлаживается (например, при сбое утверждения). Если задано header, он выводится в консоль перед началом отладки.

Изменено в версии 3.7: Только ключевой аргумент header.

pdb.post_mortem(traceback=None): Запустить пост-мортальную отладку заданного объекта traceback. Если traceback не указан, используется traceback исключения, которое в настоящее время обрабатывается (исключение должно обрабатываться, если используется значение по умолчанию).

pdb.pm(): Включить пост-мортальную отладку трассировки, найденной в sys.last_traceback.

Функции run* и set_trace() являются псевдонимами для создания экземпляра класса Pdb и вызова метода с тем же именем. Если вы хотите получить доступ к дополнительным функциям, вам нужно сделать это самостоятельно:

class pdb.Pdb(completekey='tab', stdin=None, stdout=None, skip=None, nosigint=False, readrc=True)

Pdb — класс дебаггера.

Аргументы completekey, stdin и stdout передаются в базовый класс cmd.Cmd; см. описание там.

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

По умолчанию Pdb устанавливает обработчик сигнала SIGINT (который отправляется, когда пользователь нажимает Ctrl-C в консоли) при вводе команды continue. Это позволяет снова войти в дебаггер, нажав Ctrl-C. Если вы хотите, чтобы Pdb не трогал обработчик сигнала SIGINT, установите nosigint в значение True.

Аргумент readrc по умолчанию равен True и управляет тем, загрузит ли Pdb файлы .pdbrc из файловой системы.

Пример вызова для включения отслеживания с помощью skip:

import pdb; pdb.Pdb(skip=['django.*']).set_trace()

Вызывает событие аудита pdb.Pdb без аргументов.

Новое в версии 3.1: Аргумент skip.

Новое в версии 3.2: Аргумент nosigint. Ранее Pdb никогда не устанавливал обработчик SIGINT.

Изменено в версии 3.6: Аргумент readrc.

run(statement, globals=None, locals=None)
runeval(expression, globals=None, locals=None)
runcall(function, *args, **kwds)
set_trace(): См. документацию к функциям, описанным выше.

Команды отладчика

Ниже приведены команды, распознаваемые отладчиком. Большинство команд можно сократить до одной или двух букв, как указано; например, h(elp) означает, что можно использовать h или help для ввода команды help (но не he или hel, ни H или Help или HELP). Аргументы команд должны быть разделены пробелами (пробелами или табуляцией). Необязательные аргументы заключены в квадратные скобки ([]) в синтаксисе команды; квадратные скобки вводить не нужно. Альтернативы в синтаксисе команды разделены вертикальной чертой (|).

Ввод пустой строки повторяет последнюю введенную команду. Исключение: если последняя команда была командой list, перечисляются следующие 11 строк.

Команды, которые отладчик не распознает, предполагаются Python-командами и выполняются в контексте отлаживаемой программы. Python-команды также можно префиксровать восклицательным знаком (!). Это мощный способ инспектирования отлаживаемой программы; даже возможно изменить переменную или вызвать функцию. При возникновении исключения в такой команде имя исключения выводится, но состояние отладчика не изменяется.

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

Несколько команд могут быть введены в одной строке, разделенные ;; (один ; не используется, так как это разделитель для нескольких команд в строке, передаваемой парсеру Python). Никакой интеллектуальной обработки при разделении команд не производится; входные данные разбиваются на первой паре ;;, даже если она находится посредине строковой константы. Обходной путь для строк с двойными точками с запятой — использование неявного конкатенации строк ';'';' или ";"";".

Если файл .pdbrc существует в домашнем каталоге пользователя или в текущем каталоге, он считывается с кодировкой 'utf-8' и выполняется так, как если бы он был введен в командной строке отладчика. Это особенно полезно для псевдонимов. Если оба файла существуют, файл в домашнем каталоге читается первым, и псевдонимы, определенные там, могут быть переопределены локальным файлом.

Изменено в версии 3.11: .pdbrc теперь считывается с кодировкой 'utf-8'. Ранее он считывался с кодировкой системной локали.

Изменено в версии 3.2: .pdbrc теперь может содержать команды, которые продолжают отладку, такие как continue или next. Раньше эти команды не действовали.

h(elp) [command]: Без аргумента печатает список доступных команд. С аргументом команда, выводит справку по этой команде. help pdb отображает полную документацию (строку документации модуля pdb). Поскольку аргумент команда должен быть идентификатором, необходимо ввести help exec для получения справки по команде !.

w(here): Выводит трассировку стека, начиная с последней рамки снизу. Стрелка (>) указывает текущую рамку, которая определяет контекст большинства команд.

d(own) [count]: Перемещает текущую рамку на количество (по умолчанию одно) уровней вниз по трассировке стека (к более новой рамке).

u(p) [count]: Перемещает текущую рамку на количество (по умолчанию одно) уровней вверх по трассировке стека (к более старой рамке).

b(reak) [([filename:]lineno | function) [, condition]]

С аргументом номер_строки устанавливает точку останова в этом месте в текущем файле. С аргументом функция устанавливает точку останова в первой исполняемой строке этой функции. Номер строки может быть префиксален именем файла и двоеточием, чтобы указать точку останова в другом файле (вероятно, в том, который еще не загружен). Файл ищется в sys.path. Обратите внимание, что каждой точке останова присваивается номер, с которым ссылаются все остальные команды работы с точками останова.

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

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

tbreak [([filename:]lineno | function) [, condition]]: Временная точка останова, которая автоматически удаляется при первом достижении. Аргументы такие же, как у break.

cl(ear) [filename:lineno | bpnumber ...]: С аргументом имя_файла:номер_строки очищает все точки останова в этой строке. С аргументом в виде списка номеров точек останова, разделенных пробелами, очищает эти точки останова. Без аргумента очищает все точки останова (но сначала запрашивает подтверждение).

disable [bpnumber ...]: Отключает точки останова, указанные в виде списка номеров точек останова, разделенных пробелами. Отключение точки останова означает, что она не может остановить выполнение программы, но в отличие от удаления точки останова, она остается в списке точек останова и может быть (снова) включена.

enable [bpnumber ...]: Включает указанные точки останова.

ignore bpnumber [count]: Устанавливает счетчик игнорирования для данного номера точки останова. Если количество опущено, счетчик игнорирования устанавливается в 0. Точка останова становится активной, когда счетчик игнорирования равен нулю. При отличном от нуля значении количество уменьшается каждый раз, когда достигается точка останова и она не отключена, и любое связанное условие истинно.

condition bpnumber [condition]: Устанавливает новое условие для точки останова, выражение, которое должно быть истинным, прежде чем точка останова будет активирована. Если условие отсутствует, любое существующее условие удаляется; т.е. точка останова делается безусловной.

commands [bpnumber]

Указывает список команд для точки останова с номером bpnumber. Сами команды отображаются в последующих строках. Введите строку, содержащую только end для завершения списка команд. Пример:

(Pdb) commands 1
(com) p some_variable
(com) end
(Pdb)

Чтобы удалить все команды из точки останова, введите commands и сразу же после него end; то есть, не задавайте никаких команд.

Без аргумента bpnumber, commands относится к последней установленной точке останова.

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

Указание любой команды, возобновляющей выполнение (в настоящее время continue, step, next, return, jump, quit и их сокращения) завершает список команд (как если бы эта команда сразу следовали за строкой завершения). Это происходит потому, что всякий раз, когда вы возобновляете выполнение (даже с простым next или step), вы можете встретить другую точку останова — которая может иметь свой собственный список команд, что приводит к неоднозначности относительно того, какой список следует выполнить.

Если вы используете команду silent в списке команд, обычное сообщение об остановке на точке останова не выводится. Это может быть желательно для точек останова, которые должны вывести определённое сообщение и затем продолжить. Если ни одна из других команд ничего не выводит, вы не увидите признаков того, что точка останова была достигнута.

s(tep): Выполняет текущую строку, останавливается при первой возможности (либо в вызываемой функции, либо на следующей строке в текущей функции).

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

unt(il) [lineno]

Без аргумента продолжает выполнение до тех пор, пока не будет достигнута строка с номером, большим текущего.

С аргументом номер_строки, продолжает выполнение до тех пор, пока не будет достигнута строка с номером, равным или большим номер_строки. В обоих случаях, также останавливается, когда текущая рамка возвращается.

Изменено в версии 3.2: Разрешено указать явный номер строки.

r(eturn): Продолжает выполнение до тех пор, пока текущая функция не вернётся.

c(ont(inue)): Продолжает выполнение, останавливаясь только при встрече точки останова.

END_OF_DOCUMENT_MARKER

j(ump) lineno

Установите следующую строку, которая будет выполнена. Доступно только в самом нижнем фрейме. Это позволяет перейти назад и снова выполнить код или перейти вперёд, чтобы пропустить код, который вы не хотите запускать.

Следует отметить, что не все переходы разрешены — например, невозможно перейти в середину цикла for или выйти из блока finally.

l(ist) [first[, last]]

Отобразить исходный код текущего файла. Без аргументов отобразить 11 строк вокруг текущей строки или продолжить предыдущий вывод. С . в качестве аргумента отобразить 11 строк вокруг текущей строки. С одним аргументом отобразить 11 строк вокруг указанной строки. С двумя аргументами отобразить заданный диапазон; если второй аргумент меньше первого, он интерпретируется как количество.

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

Новая функция в версии 3.2: Маркер >>.

ll | longlist: Отобразить весь исходный код текущей функции или фрейма. Интересные строки отмечаются так же, как для list.

Новая функция в версии 3.2.

a(rgs): Вывести аргументы текущей функции и их текущие значения.

p expression: Вычислить выражение в текущем контексте и вывести его значение.

Примечание

print() также может быть использовано, но это не команда отладчика — это выполняет функцию Python print().

pp expression: Подобно команде p, за исключением того, что значение выражения красиво выводится с помощью модуля pprint.

whatis expression: Вывести тип выражения.

source expression: Попытка получить исходный код выражения и отобразить его.

Новая функция в версии 3.2.

display [expression]

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

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

Примечание

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

Пример:

lst = []
breakpoint()
pass
lst.append(1)
print(lst)

Отображение не распознает, что lst изменился, потому что результат вычисления изменяется на месте модулем lst.append(1) перед сравнением:

> example.py(3)<module>()
-> pass
(Pdb) display lst
display lst: []
(Pdb) n
> example.py(4)<module>()
-> lst.append(1)
(Pdb) n
> example.py(5)<module>()
-> print(lst)
(Pdb)

Вы можете выполнить некоторые трюки с механизмом копирования, чтобы заставить это работать:

> example.py(3)<module>()
-> pass
(Pdb) display lst[:]
display lst[:]: []
(Pdb) n
> example.py(4)<module>()
-> lst.append(1)
(Pdb) n
> example.py(5)<module>()
-> print(lst)
display lst[:]: [1]  [old: []]
(Pdb)

Новая функция в версии 3.2.

undisplay [expression]: Больше не отображать выражение в текущем фрейме. Без выражения очистить все выражения отображения для текущего фрейма.

Новая функция в версии 3.2.

interact: Запустить интерактивный интерпретатор (используя модуль code), глобальное пространство имен которого содержит все имена (глобальные и локальные), найденные в текущем области.

Новая функция в версии 3.2.

alias [name [command]]

Создать псевдоним с именем имя, который выполняет команду команда. Команда команда не должна быть заключена в кавычки. Заменяемые параметры могут быть указаны как %1, %2, и так далее, при этом %* заменяется всеми параметрами. Если команда опущена, отображается текущий псевдоним для имени. Если нет аргументов, отображаются все псевдонимы.

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

В качестве примера, вот два полезных псевдонима (особенно если они размещены в файле .pdbrc):

# Print instance variables (usage "pi classInst")
alias pi for k in %1.__dict__.keys(): print(f"%1.{k} = {%1.__dict__[k]}")
# Print instance variables in self
alias ps pi self

unalias name: Удалить указанный псевдоним имя.

! statement

Выполнить (однострочное) утверждение в контексте текущей стековой рамки. Знак восклицания можно опустить, если первое слово утверждения напоминает команду отладчика. Для установки глобальной переменной можно префиксным командой присваивания утверждением global в той же строке, например:

(Pdb) global list_options; list_options = ['-l']
(Pdb)

run [args ...]
restart [args ...]: Перезапустить отлаживаемую программу Python. Если аргументы указаны, они разбиваются с помощью shlex и результат используется в качестве нового sys.argv. История, точки останова, действия и параметры отладчика сохраняются. restart является псевдонимом для run.

q(uit): Выход из отладчика. Выполняемая программа прерывается.

debug code: Войти в рекурсивный отладчик, который выполняет пошаговое выполнение кода (произвольного выражения или утверждения, которое должно быть выполнено в текущей среде).

retval: Вывести возвращаемое значение для последнего возврата текущей функции.

Приложения

1: То, считается ли фрейм происходящим из определённого модуля, определяется параметром __name__ в глобальных переменных фрейма.