pdb — отладчик Python

Интерфейс командной строки

Вы также можете вызвать pdb из командной строки для отладки других скриптов. Например:

python -m pdb [-c command] (-m module | -p pid | pyfile) [args ...]

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

-c, --command <command>

Выполнить команды, как если бы они были указаны в файле .pdbrc; см. раздел Команды отладчика.

Изменено в версии 3.2: Добавлен параметр -c.

-m <module>

Выполнять модули так же, как это делает python -m. Как и при запуске скрипта, отладчик приостановит выполнение непосредственно перед первой строкой модуля.

Изменено в версии 3.7: Добавлен параметр -m.

-p, --pid <pid>

Подключиться к процессу с указанным PID.

Добавлено в версии 3.14.

Для удалённой отладки запущенного процесса Python используйте параметр -p или --pid, указав PID целевого процесса:

python -m pdb -p 1234

Обычно для выполнения инструкции под управлением отладчика используют:

>>> import pdb
>>> def f(x):
...     print(1 / x)
>>> pdb.run("f(2)")
> <string>(1)<module>()
(Pdb) continue
0.5
>>>

Обычно для исследования аварийно завершившейся программы используют:

>>> import pdb
>>> def f(x):
...     print(1 / x)
...
>>> f(0)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 2, in f
ZeroDivisionError: division by zero
>>> pdb.pm()
> <stdin>(2)f()
(Pdb) p x
0
(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, commands=None)

Перейти в режим отладки в кадре стека вызывающего кода. Это полезно, чтобы жёстко задать точку останова в определённом месте программы, даже если код в остальном не отлаживается (например, при сбое утверждения). Если указан аргумент header, он выводится в консоль непосредственно перед началом отладки. Аргумент commands, если он указан, представляет собой список команд, выполняемых при запуске отладчика.

Изменено в версии 3.7: Добавлен именованный аргумент header.

Изменено в версии 3.13: set_trace() теперь немедленно переходит в режим отладки, а не на следующей строке кода, которая должна быть выполнена.

Добавлено в версии 3.14: Аргумент commands.

awaitable pdb.set_trace_async(*, header=None, commands=None)

Асинхронная версия set_trace(). Эту функцию следует использовать внутри асинхронной функции с await.

async def f():
    await pdb.set_trace_async()

Инструкции await поддерживаются, если отладчик запущен этой функцией.

Добавлено в версии 3.14.

pdb.post_mortem(t=None)

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

Изменено в версии 3.13: Добавлена поддержка объектов исключений.

pdb.pm()

Перейти к отладке после завершения программы для исключения, найденного в sys.last_exc.

pdb.set_default_backend(backend)

Для pdb поддерживаются две серверные реализации: 'settrace' и 'monitoring'. Подробнее см. bdb.Bdb. Пользователь может задать серверную реализацию по умолчанию, которая будет использоваться, если при создании экземпляра Pdb она не указана. Если серверная реализация не указана, по умолчанию используется 'settrace'.

Примечание

На breakpoint() и set_trace() эта функция не влияет. Они всегда используют серверную реализацию 'monitoring'.

Добавлено в версии 3.14.

pdb.get_default_backend()

Возвращает серверную реализацию pdb по умолчанию.

Добавлено в версии 3.14.

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

class pdb.Pdb(completekey='tab', stdin=None, stdout=None, skip=None, nosigint=False, readrc=True, mode=None, backend=None, colorize=False)

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

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

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

По умолчанию Pdb устанавливает обработчик сигнала SIGINT (который отправляется при нажатии Ctrl-C в консоли), когда вы вводите команду continue. Это позволяет снова перейти в режим отладки, нажав Ctrl-C. Чтобы Pdb не изменял обработчик SIGINT, задайте для nosigint значение true.

Аргумент readrc по умолчанию равен true и определяет, будет ли Pdb загружать файлы .pdbrc из файловой системы.

Аргумент mode указывает, каким способом был запущен отладчик. Он влияет на работу некоторых команд отладчика. Допустимые значения: 'inline' (используется встроенной функцией breakpoint()), 'cli' (используется при запуске из командной строки) или None (для обратной совместимости с поведением до добавления аргумента mode).

Аргумент backend задаёт серверную реализацию отладчика. Если передано None, будет использоваться реализация по умолчанию. См. set_default_backend(). В противном случае поддерживаются реализации 'settrace' и 'monitoring'.

Если аргумент colorize задан как True, в отладчике будет включён цветной вывод, если поддерживается цвет. Это позволит выделять цветом отображаемый в pdb исходный код.

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

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

Вызывает событие аудита pdb.Pdb без аргументов.

Изменено в версии 3.1: Добавлен параметр skip.

Изменено в версии 3.2: Добавлен параметр nosigint. Ранее Pdb никогда не устанавливал обработчик SIGINT.

Изменено в версии 3.6: Добавлен аргумент readrc.

Добавлено в версии 3.14: Добавлен аргумент mode.

Добавлено в версии 3.14: Добавлен аргумент backend.

Добавлено в версии 3.14: Добавлен аргумент colorize.

Изменено в версии 3.14: Встроенные точки останова, такие как breakpoint() или pdb.set_trace(), всегда будут останавливать программу в кадре вызывающего кода, игнорируя шаблон skip (если он задан).

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.) При разделении команд не учитывается контекст; ввод разбивается по первой паре ;;, даже если она находится внутри строки в кавычках. Для строк с двойной точкой с запятой можно использовать неявную конкатенацию строк: ';'';' или ";"";".

Чтобы задать временную глобальную переменную, используйте удобную переменную. Удобная переменная — это переменная, имя которой начинается с $. Например, $foo = 1 задаёт глобальную переменную $foo, которую можно использовать в сеансе отладчика. Удобные переменные очищаются при возобновлении выполнения программы, поэтому вероятность их влияния на программу ниже, чем при использовании обычных переменных, например foo = 1.

Существует четыре предустановленные удобные переменные:

• $_frame: текущий отлаживаемый кадр
• $_retval: возвращаемое значение, если кадр возвращает управление
• $_exception: исключение, если кадр вызывает исключение
• $_asynctask: задача asyncio, если pdb останавливается в асинхронной функции

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

h(elp) [command]

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

w(here) [count]

Выводит трассировку стека, помещая самый свежий кадр внизу. Если count равен 0, выводится запись текущего кадра. Если count отрицателен, выводятся самые ранние кадры — count кадров. Если count положителен, выводятся count самых свежих кадров. Стрелка (>) указывает на текущий кадр, определяющий контекст для большинства команд.

Изменено в версии 3.14: Добавлен аргумент count.

d(own) [count]

Перемещает текущий кадр вниз по трассировке стека на count уровней (по умолчанию на один), к более свежему кадру.

u(p) [count]

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

b(reak) [([filename:]lineno | function) [, condition]]

Если указан аргумент lineno, устанавливает точку останова на строке lineno в текущем файле. Перед номером строки можно указать filename и двоеточие, чтобы установить точку останова в другом файле (возможно, ещё не загруженном). Поиск файла выполняется в sys.path. Допустимые варианты filename: /abspath/to/file.py, relpath/file.py, module и package.module.

Если указан аргумент function, устанавливает точку останова на первой исполняемой инструкции этой функции. function может быть любым выражением, результатом вычисления которого в текущем пространстве имён является функция.

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

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

Каждой точке останова присваивается номер, на который ссылаются все остальные команды управления точками останова.

tbreak [([filename:]lineno | function) [, condition]]

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

cl(ear) [filename:lineno | bpnumber ...]

Если указан аргумент filename:lineno, удаляет все точки останова на этой строке. Если указан разделённый пробелами список номеров точек останова, удаляет эти точки. Без аргументов удаляет все точки останова (предварительно запрашивая подтверждение).

disable bpnumber [bpnumber ...]

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

enable bpnumber [bpnumber ...]

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

ignore bpnumber [count]

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

condition bpnumber [condition]

Задаёт новое условие для точки останова — выражение, результатом вычисления которого должно быть значение true, чтобы точка останова сработала. Если 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, until, jump, quit и их сокращения) завершает список команд, как если бы сразу после этой команды стоял признак конца ввода. Это необходимо, поскольку при возобновлении выполнения (даже с помощью простой команды next или step) может встретиться другая точка останова, у которой может быть собственный список команд. В таком случае было бы неясно, какой список выполнять.

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

Изменено в версии 3.14: Информация о кадре не выводится, если список команд содержит команду, возобновляющую выполнение.

s(tep)

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

n(ext)

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

unt(il) [lineno]

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

Если указан lineno, продолжает выполнение до достижения строки с номером, большим или равным 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

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

Примечание

Можно также использовать print(), но это не команда отладчика — она вызывает функцию Python print().

pp expression

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

whatis expression

Выводит тип expression.

source expression

Пытается получить исходный код expression и вывести его.

Добавлено в версии 3.2.

display [expression]

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

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

Примечание

Команда display вычисляет expression и сравнивает результат с результатом предыдущего вычисления expression, поэтому при изменяемом результате команда display может не обнаружить изменения.

Пример:

lst = []
breakpoint()
pass
lst.append(1)
print(lst)

Команда display не обнаружит изменение lst, поскольку результат вычисления изменяется на месте командой lst.append(1) до сравнения:

> example.py(3)<module>()
-> pass
(Pdb) display lst
display lst: []
(Pdb) n
> example.py(4)<module>()
-> lst.append(1)
(Pdb) n
> example.py(5)<module>()
-> print(lst)
(Pdb)

Чтобы это исправить, можно воспользоваться копированием:

> example.py(3)<module>()
-> pass
(Pdb) display lst[:]
display lst[:]: []
(Pdb) n
> example.py(4)<module>()
-> lst.append(1)
(Pdb) n
> example.py(5)<module>()
-> print(lst)
display lst[:]: [1]  [old: []]
(Pdb)

Добавлено в версии 3.2.

undisplay [expression]

Перестаёт выводить expression в текущем кадре. Без аргумента удаляет все выражения для отображения в текущем кадре.

Добавлено в версии 3.2.

interact

Запускает интерактивный интерпретатор (с помощью модуля code) в новом глобальном пространстве имён, инициализированном локальным и глобальным пространствами имён текущей области видимости. Используйте exit() или quit(), чтобы выйти из интерпретатора и вернуться к отладчику.

Примечание

Поскольку interact создаёт отдельное пространство имён для выполнения кода, присваивания переменным не влияют на исходные пространства имён. Однако изменения любых связанных изменяемых объектов, как обычно, отразятся в исходных пространствах имён.

Добавлено в версии 3.2.

Изменено в версии 3.13: Для выхода из команды interact можно использовать exit() и quit().

Изменено в версии 3.13: Вывод команды interact направляется в канал вывода отладчика, а не в sys.stderr.

alias [name [command]]

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

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

(Pdb) ! n=42
(Pdb)

Чтобы задать глобальную переменную, можно поставить перед командой присваивания инструкцию global в той же строке, например:

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

run [args ...]

restart [args ...]

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

Изменено в версии 3.14: Команды run и restart отключены, если отладчик запущен в режиме 'inline'.

q(uit)

Завершает работу отладчика. Выполняемая программа прерывается. Ввод конца файла равнозначен команде quit.

Если отладчик запущен в режиме 'inline', появится запрос подтверждения. Для подтверждения завершения введите y, Y, <Enter> или EOF.

Изменено в версии 3.14: Если отладчик запущен в режиме 'inline', появится запрос подтверждения. После подтверждения отладчик немедленно вызовет sys.exit() вместо того, чтобы вызвать исключение bdb.BdbQuit при следующем событии трассировки.

debug code

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

retval

Выводит значение, возвращённое при последнем возврате из текущей функции.

exceptions [excnumber]

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

При использовании pdb.pm() или Pdb.post_mortem(...) с цепочкой исключений вместо трассировки стека можно перемещаться между связанными исключениями: команда exceptions выводит список исключений, а exceptions <number> переключается на указанное исключение.

Пример:

def out():
    try:
        middle()
    except Exception as e:
        raise ValueError("reraise middle() error") from e

def middle():
    try:
        return inner(0)
    except Exception as e:
        raise ValueError("Middle fail")

def inner(x):
    1 / x

 out()

вызов pdb.pm() позволит переключаться между исключениями:

> example.py(5)out()
-> raise ValueError("reraise middle() error") from e

(Pdb) exceptions
  0 ZeroDivisionError('division by zero')
  1 ValueError('Middle fail')
> 2 ValueError('reraise middle() error')

(Pdb) exceptions 0
> example.py(16)inner()
-> 1 / x

(Pdb) up
> example.py(10)middle()
-> return inner(0)

Добавлено в версии 3.13.

Сноски