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)

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

python3 -m pdb myscript.py

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

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

import pdb; pdb.set_trace()

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

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

>>> 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()

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

pdb.post_mortem(traceback=None)

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

pdb.pm()

Входим в пост-мортем отладку стека отслеживания, найденного в sys.last_traceback.

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

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

Pdb — класс отладчика.

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

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

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

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

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

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

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

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

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

runcall(function, *args, **kwds)

set_trace()

См. документацию к функциям, описанным выше.

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

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

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

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

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

Несколько команд можно ввести в одной строке, разделённые ;;. (Один ; не используется, так как это разделитель для нескольких команд в строке, которая передаётся в парсер Python.) Интеллектуальное разделение команд не применяется; ввод разделяется на пары ;;, даже если он находится в середине строковой литералы.

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

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 [bpnumber ...]]

С аргументом имя_файла:номер_строки очищает все точки останова на этой строке. Со списком номеров точек останова через пробел, очищает эти точки останова. Без аргумента очищает все точки останова (но сначала запросит подтверждение).

disable [bpnumber [bpnumber ...]]

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

enable [bpnumber [bpnumber ...]]

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

ignore bpnumber [count]

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

condition bpnumber [condition]

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

commands [bpnumber]

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

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

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

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

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

Указание любой команды, возобновляющей выполнение (в настоящее время continue, step, next, return, jump, quit и их сокращения) завершает список команд (как если бы эта команда следовал за end). Это связано с тем, что каждый раз, когда вы возобновляете выполнение (даже с простым 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)

Выйти из отладчика. Выполняемая программа прерывается.

Примечания