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

python -m pdb myscript.py

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

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

import pdb; pdb.set_trace()

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

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

>>> 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[, locals]])

Выполнить оператор (переданный как строка) под управлением отладчика. Подсказка отладчика появляется перед выполнением любого кода; вы можете установить точки останова и набрать continue, или вы можете выполнить пошаговое выполнение оператора с помощью step или next (все эти команды описаны ниже). Дополнительные аргументы globals и locals указывают среду, в которой выполняется код; по умолчанию используется словарь модуля __main__. (См. описание оператора exec или встроенной функции eval().)

pdb.runeval(expression[, globals[, locals]])

Вычислить выражение (переданное как строка) под управлением отладчика. Когда runeval() возвращает значение, оно возвращает значение выражения. В противном случае эта функция аналогична run().

pdb.runcall(function[, argument, ...])

Вызвать функцию (объект функции или метода, а не строку) с заданными аргументами. Когда runcall() возвращает значение, оно возвращает то, что вернула функция. Подсказка отладчика появляется сразу после входа в функцию.

pdb.set_trace()

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

pdb.post_mortem([traceback])

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

pdb.pm()

Перейти в пост-мортальную отладку для traceback, найденного в sys.last_traceback.

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

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

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

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

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

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

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

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

run(statement[, globals[, locals]])

runeval(expression[, globals[, locals]])

runcall(function[, argument, ...])

set_trace()

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

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

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

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

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

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

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

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

h(elp) [команда]

Без аргумента выводит список доступных команд. С аргументом команда выводит справку по этой команде. help pdb отображает полный файл документации; если переменная среды PAGER определена, файл передаётся в эту команду. Поскольку аргумент команда должен быть идентификатором, для получения справки по команде ! необходимо ввести help exec.

w(here)

Выводит трассировку стека, где самая последняя рамка находится внизу. Стрелка указывает текущую рамку, которая определяет контекст большинства команд.

d(own)

Перемещает текущую рамку на один уровень вниз в трассировке стека (к более новой рамке).

u(p)

Перемещает текущую рамку на один уровень вверх в трассировке стека (к более старой рамке).

b(reak) [[имя_файла:]номер_строки | функция[, условие]]

С аргументом номер_строки устанавливает точку останова в текущем файле. С аргументом функция устанавливает точку останова в первой исполняемой строке этой функции. Номер строки можно задать с префиксом имени файла и двоеточием, чтобы указать точку останова в другом файле (вероятно, в том, который ещё не загружен). Файл ищется в sys.path. Обратите внимание, что каждой точке останова присваивается номер, к которому ссылаются все остальные команды точки останова.

Если присутствует второй аргумент, это выражение, которое должно быть истинным, прежде чем точка останова будет учтена.

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

tbreak [[имя_файла:]номер_строки | функция[, условие]]

Временная точка останова, которая автоматически удаляется при первом её достижении. Аргументы такие же, как у break.

cl(ear) [имя_файла:номер_строки | номер_точки_останова [номер_точки_останова …]]

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

disable [номер_точки_останова [номер_точки_останова …]]

Отключает указанные точки останова, перечисленные через пробел, по номерам.

enable [номер_точки_останова [номер_точки_останова …]]

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

ignore номер_точки_останова [счёт]

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

condition номер_точки_останова [условие]

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

commands [номер_точки_останова]

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

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

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

Без аргумента номер_точки_останова commands относится к последней установленной точке останова.

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

Указание любой команды, возобновляющей выполнение (в настоящее время continue, step, next, return, jump, quit и их сокращения) завершает список команд (как если бы эта команда была сразу после end). Это связано с тем, что каждый раз, когда вы возобновляете выполнение (даже с простым next или step), вы можете встретить другую точку останова — которая может иметь свой собственный список команд, что приводит к неоднозначности относительно того, какой список выполнять.

Если вы используете команду «silent» в списке команд, обычное сообщение об остановке на точке останова не выводится. Это может быть желательно для точек останова, которые должны вывести конкретное сообщение и затем продолжить. Если ни одна из других команд ничего не выводит, вы не увидите никаких признаков того, что точка останова была достигнута.

Новая версия 2.5.

s(tep)

Выполняет текущую строку, останавливается при первой возможности (либо в вызываемой функции, либо в следующей строке в текущей функции).

n(ext)

Продолжает выполнение, пока не будет достигнута следующая строка в текущей функции или не произойдёт возврат. (Разница между next и step заключается в том, что step останавливается внутри вызываемой функции, в то время как next выполняет вызываемые функции со (практически) полной скоростью, останавливаясь только на следующей строке в текущей функции.)

unt(il)

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

Новая версия 2.6.

r(eturn)

Продолжает выполнение, пока текущая функция не вернётся.

c(ont(inue))

Продолжает выполнение, останавливаясь только при достижении точки останова.

j(ump) номер_строки

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

Следует отметить, что не все прыжки разрешены — например, невозможно перейти в середину цикла for или выйти из блока finally.

l(ist) [первая[, последняя]]

Выводит исходный код для текущего файла. Без аргументов выводит 11 строк вокруг текущей строки или продолжает предыдущий вывод. С одним аргументом выводит 11 строк вокруг этой строки. С двумя аргументами выводит заданный диапазон; если второй аргумент меньше первого, он интерпретируется как счёт.

a(rgs)

Выводит список аргументов текущей функции.

p выражение

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

Примечание

print также можно использовать, но это не команда отладчика — это выполняет оператор Python print.

pp выражение

Аналогично команде p, за исключением того, что значение выражения форматируется с помощью модуля pprint.

alias [имя [команда]]

Создаёт псевдоним с именем имя, который выполняет команду. Команда не должна заключаться в кавычки. Заменяемые параметры можно указать как %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 имя

Удаляет указанный псевдоним.

[!]оператор

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

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

run [аргументы …]

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

Новая версия 2.6.

q(uit)

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

Примечания

1

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