pdb — Налагоджувач Python

Kod źródłowy: Lib/pdb.py

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

Налагоджувач є розширюваним - він фактично визначений як клас Pdb. Наразі це незадокументовано, але легко зрозуміти, прочитавши джерело. Інтерфейс розширення використовує модулі bdb і cmd.

Zobacz także

Модуль faulthandler

Используется для явного сброса обратных трассировок Python, при ошибке, после тайм-аута или по сигналу пользователя.

Модуль traceback

Стандартный интерфейс для извлечения, форматирования и печати трассировок стека программ Python.

Типовим використанням для проникнення в налагоджувач є вставка:

import pdb; pdb.set_trace()

Или:

breakpoint()

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

Zmienione w wersji 3.7: Встроенную функцию breakpoint(), вызываемую с настройками по умолчанию, можно использовать вместо import pdb; pdb.set_trace().

def double(x):
   breakpoint()
   return x * 2
val = 3
print(f"{val} * 2 is {double(val)}")

Приглашение отладчика — (Pdb), которое указывает на то, что вы находитесь в режиме отладки:

> ...(2)double()
-> breakpoint()
(Pdb) p x
3
(Pdb) continue
3 * 2 is 6

Zmienione w wersji 3.3: Завершення табуляції через модуль readline доступне для команд і аргументів команд, напр. поточні глобальні та локальні імена пропонуються як аргументи команди p.

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

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

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

-c, --command <command>

Para executar comandos como se fossem dados em um arquivo .pdbrc. Veja Команди налагоджувача.

Zmienione w wersji 3.2: Adicionada a opção -c.

-m <module>

Para executar módulos de maneira similar ao python -m. Assim como em um script, o depurador pausará a execução logo antes da primeira linha do módulo.

Zmienione w wersji 3.7: Adicionada a opção -m.

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

>>> 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)

Zmienione w wersji 3.13: Реализация PEP 667 означает, что назначения имен, сделанные через 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)

Enter the debugger at the calling stack frame. This is useful to hard-code a breakpoint at a given point in a program, even if the code is not otherwise being debugged (e.g. when an assertion fails). If given, header is printed to the console just before debugging begins.

Zmienione w wersji 3.7: Лише ключовий аргумент header.

Zmienione w wersji 3.13: set_trace() войдет в отладчик сразу, а не на следующей строке кода, которая будет выполнена.

pdb.post_mortem(t=None)

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

Zmienione w wersji 3.13: Adiciona suporte a objetos exceção.

pdb.pm()

Введите посмертную отладку исключения, найденного в sys.last_exc.

Функції 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 без аргументів.

Zmienione w wersji 3.1: Добавлен параметр skip.

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

Zmienione w wersji 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 або Довідка або ДОПОМОГА). Аргументи команд повинні бути розділені пробілами (пробілами або табуляцією). Необов’язкові аргументи в синтаксисі команди беруться у квадратні дужки ([]); квадратні дужки не можна вводити. Альтернативи в синтаксисі команди розділені вертикальною рискою (|).

Введення порожнього рядка повторює останню введену команду. Виняток: якщо останньою командою була команда list, буде показано наступні 11 рядків.

Команди, які не розпізнає налагоджувач, вважаються операторами Python і виконуються в контексті програми, що налагоджується. Інструкції Python також можуть мати префікс знаком оклику (!). Це потужний спосіб перевірити програму, яка налагоджується; можна навіть змінити змінну або викликати функцію. Коли в такому операторі виникає виняток, ім’я виключення друкується, але стан налагоджувача не змінюється.

Zmienione w wersji 3.13: Выражения/операторы, префиксом которых является команда pdb, теперь правильно идентифицируются и выполняются.

Налагоджувач підтримує псевдоніми. Псевдоніми можуть мати параметри, які дозволяють певний рівень адаптації до досліджуваного контексту.

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

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

There are three preset convenience variables:

  • $_frame: текущий кадр, который вы отлаживаете.

  • $_retval: возвращаемое значение, если кадр возвращается.

  • $_Exception: исключение, если кадр вызывает исключение.

Dodane w wersji 3.12: Добавлена ​​функция удобная переменная.

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

Zmienione w wersji 3.2: .pdbrc тепер може містити команди, які продовжують налагодження, наприклад continue або next. Раніше ці команди не діяли.

Zmienione w wersji 3.11: .pdbrc теперь читается с кодировкой 'utf-8'. Раньше он читался с использованием системной языковой кодировки.

h(elp) [command]

Без аргументів вивести список доступних команд. З командою як аргументом надрукуйте довідку про цю команду. help pdb відображає повну документацію (рядок документації модуля pdb). Оскільки аргумент command має бути ідентифікатором, необхідно ввести help exec, щоб отримати довідку щодо команди !.

w(here)

Print a stack trace, with the most recent frame at the bottom. An arrow (>) indicates the current frame, which determines the context of most commands.

d(own) [count]

Перемістіть поточний кадр кількість (за замовчуванням) на рівні трасування стека (до нового кадру).

u(p) [count]

Перемістити поточний кадр кількість (за замовчуванням) вгору в трасуванні стека (до старішого кадру).

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

With a lineno argument, set a break at line lineno in the current file. The line number may be prefixed with a filename and a colon, to specify a breakpoint in another file (possibly one that hasn’t been loaded yet). The file is searched on sys.path. Accepatable forms of filename are /abspath/to/file.py, relpath/file.py, module and package.module.

С помощью аргумента 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, перш ніж точка зупину буде виконана. Якщо умова відсутня, усі наявні умови видаляються; тобто точка зупину стає безумовною.

commands [bpnumber]

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

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

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

Без аргументу bpnumber commands посилається на останній набір точок зупину.

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

Specifying any command resuming execution (currently continue, step, next, return, jump, quit and their abbreviations) terminates the command list (as if that command was immediately followed by end). This is because any time you resume execution (even with a simple next or step), you may encounter another breakpoint—which could have its own command list, leading to ambiguities about which list to execute.

If you use the silent command in the command list, the usual message about stopping at a breakpoint is not printed. This may be desirable for breakpoints that are to print a specific message and then continue. If none of the other commands print anything, you see no sign that the breakpoint was reached.

s(tep)

Виконати поточний рядок, зупинитися при першому можливому випадку (або у функції, яка викликається, або на наступному рядку в поточній функції).

n(ext)

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

unt(il) [lineno]

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

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

Zmienione w wersji 3.2: Дозволяє вказувати явний номер рядка.

r(eturn)

Продовжуйте виконання, доки поточна функція не повернеться.

c(ont(inue))

Продовжувати виконання, зупинятися лише тоді, коли зустрічається точка зупину.

j(ump) lineno

Встановіть наступний рядок, який буде виконано. Доступно лише в нижній рамці. Це дає змогу повернутися назад і виконати код знову або перейти вперед, щоб пропустити код, який ви не хочете запускати.

Слід зазначити, що не всі переходи дозволені - наприклад, неможливо перейти в середину циклу for або з пункту finally.

l(ist) [first[, last]]

Список вихідного коду для поточного файлу. Без аргументів перелічити 11 рядків навколо поточного рядка або продовжити попередній список. З аргументом . перелічити 11 рядків навколо поточного рядка. З одним аргументом перелічіть 11 рядків навколо цього рядка. З двома аргументами перелічіть заданий діапазон; якщо другий аргумент менший за перший, він інтерпретується як підрахунок.

Поточний рядок у поточному кадрі позначається ->. Якщо виняток налагоджується, рядок, де виняток було спочатку викликано або поширено, позначається >>, якщо він відрізняється від поточного рядка.

Zmienione w wersji 3.2: Добавлен маркер >>.

ll | longlist

Перерахувати весь вихідний код для поточної функції або кадру. Цікаві рядки позначені як для list.

Dodane w wersji 3.2.

a(rgs)

Выведите аргументы текущей функции и их текущие значения.

p expression

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

Informacja

print() також можна використовувати, але це не команда відладчика — вона виконує функцію print() Python.

pp expression

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

whatis expression

Выведите тип выражения.

source expression

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

Dodane w wersji 3.2.

display [expression]

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

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

Informacja

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

Przykład:

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

Дисплей не поймет, что 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)

Dodane w wersji 3.2.

undisplay [expression]

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

Dodane w wersji 3.2.

interact

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

Informacja

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

Dodane w wersji 3.2.

Zmienione w wersji 3.13: exit() и quit() можно использовать для выхода из команды interact.

Zmienione w wersji 3.13: interact направляет свои выходные данные в выходной канал отладчика, а не в sys.stderr.

alias [name [command]]

Создайте псевдоним с именем имя, который выполняет команду. Команду нельзя заключать в кавычки. Заменяемые параметры могут обозначаться %1, %2, … и %9, а %* заменяется всеми параметрами. Если команда опущена, отображается текущий псевдоним для имя. Если аргументы не указаны, отображаются все псевдонимы.

Псевдоніми можуть бути вкладеними та можуть містити будь-що, що можна легально ввести в підказці 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

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

! 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)

Quit from the debugger. The program being executed is aborted.

debug code

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

retval

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

exceptions [excnumber]

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

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

Przykład:

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)

Dodane w wersji 3.13.

Przypisy