pdb — Дебаггер Python

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

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

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

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

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

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

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

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

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

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

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

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

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]: Устанавливает счетчик игнорирования для данного номера точки останова. Если 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)): Продолжает выполнение, останавливаясь только при достижении точки останова.

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]

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

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

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

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

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

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

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

alias [name [command]]

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

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

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

# Print instance variables (usage "pi classInst")
alias pi for k in %1.__dict__.keys(): print("%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__ в глобальных переменных области отображения.