pdb — Дебаггер Python

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

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

Дебаггер расширяем — он фактически определяется как класс Pdb. В настоящее время это недокументировано, но легко понять, прочитав исходный код. Интерфейс расширения использует модули bdb и cmd.

См. также

Module faulthandler: Используется для явного вывода отладочных трассировок Python при ошибках, по истечении таймаута или при сигнале пользователя.
Module traceback: Стандартный интерфейс для извлечения, форматирования и вывода стековых трассировок программ Python.

Подсказка дебаггера — (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 также можно вызвать как скрипт для отладки других скриптов. Например:

python -m pdb myscript.py

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

Новое в версии 3.2: pdb.py теперь принимает опцию -c, которая выполняет команды, как будто они заданы в файле .pdbrc, см. Команды дебаггера.

Новое в версии 3.7: pdb.py теперь принимает опцию -m, которая выполняет модули аналогично тому, как это делает python -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): Войти в дебаггер в стековом фрейме вызова. Это полезно для вставки точки останова в определённой точке программы, даже если код не отлаживается иначе (например, когда срабатывает утверждение). Если задано, заголовок выводится в консоль перед началом отладки.

Изменено в версии 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()

Вызывает событие отладки 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]: Перемещает текущий фрейм вниз по трассировке стека на количество (по умолчанию 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]: Устанавливает счётчик игнорирования для заданного номера точки останова. Если количество опущено, счётчик игнорирования устанавливается в 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. command не должен быть заключен в кавычки. Заменяемые параметры могут быть указаны как %1, %2, и так далее, а %* заменяет все параметры. Если command пропущен, отображается текущий псевдоним для name. Если аргументов нет, отображаются все псевдонимы.

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

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

# Print instance variables (usage "pi classInst")
alias pi for k in %1.__dict__.keys(): print(f"%1.{k} = {%1.__dict__[k]}")
# Print instance variables in self
alias ps pi self

unalias name: Удалить указанный псевдоним name.

! statement

Выполнить (однострочное) statement в контексте текущего стекового фрейма. Знак восклицания можно опустить, если первое слово оператора напоминает команду отладчика. Для установки глобальной переменной вы можете добавить перед командой присваивания оператор global в той же строке, например:

(Pdb) global list_options; list_options = ['-l']
(Pdb)

run [args ...]
restart [args ...]: Перезапустить отлаживаемую программу Python. Если указан args, он разделится с помощью shlex, и результат используется в качестве нового sys.argv. История, точки останова, действия и параметры отладчика сохраняются. restart является псевдонимом для run.

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

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

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

Примечания

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