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, для ввода команды 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]: Перемещает текущий кадр на count (по умолчанию 1) уровней вниз по трассировке стека (к более позднему кадру).

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

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]: Устанавливает новое условие для точки останова, выражение, которое должно быть истинным, прежде чем точка останова будет активирована. Если условие отсутствует, любое существующее условие удаляется; т.е., точка останова становится безусловной.

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 и их сокращения) завершает список команд (как если бы эта команда следовала непосредственно за 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): Выйти из отладчика. Выполняемая программа прерывается.

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

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

Примечания

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