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(*, header=None)

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

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

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, 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. Ранее 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 существует в домашнем каталоге пользователя или в текущем каталоге, он считывается и выполняется так, как если бы он был введён в командной строке отладчика. Это особенно полезно для псевдонимов. Если оба файла существуют, сначала считывается файл в домашнем каталоге, а псевдонимы, определённые в нём, могут быть переопределены локальным файлом.

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]

Устанавливает счёт игнорирования для заданного номера точки останова. Если счёт опущен, счёт игнорирования устанавливается в 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

Print the return value for the last return of a function.

Примечания

1

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