pdb — Python отладчик

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

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

Приглашение отладчика — (Pdb). Типичное использование для запуска программы под управлением отладчика:

>>> import pdb
>>> import mymodule
>>> pdb.run('mymodule.test()')
> <string>(0)?()
(Pdb) continue
> <string>(1)?()
(Pdb) continue
NameError: 'spam'
> <string>(1)?()
(Pdb)

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

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

python3 -m pdb myscript.py

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

Добавлено в версии 3.2: pdb.py теперь принимает параметр -c, который выполняет команды, как если бы они были заданы в файле .pdbrc, см. Команды отладчика.

Добавлено в версии 3.7: pdb.py теперь принимает опцию -m, которая выполняет модули, аналогичные тому, как это делает python3 -m. Как и в случае со сценарием, отладчик приостановит выполнение непосредственно перед первой строкой модуля.

Типичное использование для перехода в отладчик из работающей программы — вставка

import pdb; pdb.set_trace()

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

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

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

>>> import pdb
>>> import mymodule
>>> mymodule.test()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "./mymodule.py", line 4, in test
    test2()
  File "./mymodule.py", line 3, in test2
    print(spam)
NameError: spam
>>> pdb.pm()
> ./mymodule.py(3)test2()
-> print(spam)
(Pdb)

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

pdb.run(statement, globals=None, locals=None)

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

pdb.runeval(expression, globals=None, locals=None)

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

pdb.runcall(function, *args, **kwds)

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

pdb.set_trace(*, header=None)

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

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

pdb.post_mortem(traceback=None)

Входит в посмертную отладку данного объекта 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 истинное значение.

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

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

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

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

Добавлено в версии 3.1: Аргумент skip.

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

Изменено в версии 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 (но не he или hel, а также H или Help или HELP). Аргументы команд должны быть разделены пробелами (пробелами или табуляцией). Необязательные аргументы заключены в квадратные скобки ([]) в синтаксисе команды; квадратные скобки не должны быть напечатаны. Альтернативы в синтаксисе команды разделены вертикальной чертой (|).

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

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

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

В одной строке можно ввести несколько команд, разделенных ;;. (Один ; не используется, т. к. он является разделителем для нескольких команд в строке, которая передаётся парсеру Python.) Для разделения команд не применяются никакие интеллектуальные функции; ввод разбивается на первую пару ;;, даже если она находится в середине строки в кавычках.

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

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

h(elp) [command]

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

w(here)

Распечатывает трассировку стека с самым последним фреймом внизу. Стрелка указывает на текущий фрейм, который определяет контекст большинства команд.

d(own) [count]

Перемещает текущий фрейм count (по умолчанию) на уровень вниз в трассировке стека (к более новому фрейму).

u(p) [count]

Перемещает текущий фрейм count (по умолчанию) на уровень выше в трассировке стека (к более старому фрейму).

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

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

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

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

tbreak [([filename:]lineno | function) [, condition]]

Временная точка останова, которая удаляется автоматически при первом попадании. Аргументы те же, что и для break.

cl(ear) [filename:lineno | bpnumber [bpnumber ...]]

С помощью аргумента filename:lineno удаляет все точки останова на этой строке. Со списком номеров точек останова, разделенных пробелами, удаляет данные точки останова. Без аргументов очищает все прерывания (но сначала запрашивает подтверждение).

disable [bpnumber [bpnumber ...]]

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

enable [bpnumber [bpnumber ...]]

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

ignore bpnumber [count]

Устанавливает счётчик игнорирования для заданного номера точки останова. Если count пропущен, счётчик игнорирования устанавливается равным 0. Точка останова становится активной, когда счётчик игнорирования равен нулю. Когда значение не равно нулю, счётчик уменьшается каждый раз, когда достигается точка останова, и точка останова не отключена, а любое связанное условие оценивается как истинное.

condition bpnumber [condition]

Устанавливает новый condition для точки останова, выражение, которое должно быть истинным, прежде чем точка останова будет принята. Если 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 и их аббревиатуры), завершает список команд (как если бы за этой командой сразу же следовал конец). Это связано с тем, что каждый раз, когда вы возобновляете выполнение (даже с помощью простого следующего или шага), вы можете столкнуться с другой точкой останова, которая может иметь свой собственный список команд, что приводит к неоднозначности в отношении того, какой список выполнять.

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

s(tep)

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

n(ext)

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

unt(il) [lineno]

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

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

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

r(eturn)

Продолжать выполнение, пока текущая функция не вернется.

c(ont(inue))

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

j(ump) lineno

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

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

l(ist) [first[, last]]

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

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

Добавлено в версии 3.2: Маркер >>.

ll | longlist

Перечисляет весь исходный код для текущей функции или фрейма. Интересные строки отмечены как для list.

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

a(rgs)

Распечатывает список аргументов текущей функции.

p expression

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

Примечание

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

pp expression

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

whatis expression

Распечатывает тип expression.

source expression

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

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

display [expression]

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

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

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

undisplay [expression]

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

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

interact

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

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

alias [name [command]]

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

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

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

# Печать переменных экземпляра (использование "pi classInst")
alias pi for k in %1.__dict__.keys(): print("%1.",k,"=",%1.__dict__[k])
# Печатать переменные экземпляра в self
alias ps pi self
unalias name

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

! statement

Выполняет (однострочный) 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__ в глобальных переменных фрейма.