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)

Перейти в пост-мортем дебаггер заданного объекта трассировки. Если 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()

Добавлена в версии 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()

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

27.3.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]

Перемещает текущую рамку на 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)

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

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

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

Указание любой команды, возобновляющей выполнение (в настоящее время 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]]

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

Псевдонимы могут быть вложены и могут содержать всё, что может быть введено в командной строке 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)

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

Примечания

1

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