pdb — Отладчик Python

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

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

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

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

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

В одной строке можно ввести несколько команд, разделив их символом ;;. (Один символ ; не используется, так как он служит разделителем нескольких команд в строке, передаваемой анализатору Python.) Команды разделяются без учёта контекста; ввод разбивается по первой паре ;;, даже если она находится внутри строки в кавычках. Для строк с двойными точками с запятой можно использовать неявную конкатенацию строк ';'';' или ";"";".

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

Предусмотрены три переменные удобства:

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

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

h(elp) [command]

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

w(here)

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

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 может быть любым выражением, которое вычисляется в функцию в текущем пространстве имён.

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

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

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

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]

Задаёт новое condition для точки останова — выражение, которое должно вычислиться в истинное значение, чтобы точка останова сработала. Если 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]

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

Если указан 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 в текущем кадре. Без аргумента 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

Выполняет (однострочную) 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.

q(uit)

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

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.

Сноски