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

Вихідний код: Lib/pdb.py

---

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

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

Дивись також

Module faulthandler

Used to dump Python tracebacks explicitly, on a fault, after a timeout, or on a user signal.

Module traceback

Standard interface to extract, format and print stack traces of Python programs.

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

import pdb; pdb.set_trace()

Or:

breakpoint()

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

Змінено в версії 3.7: The built-in breakpoint(), when called with defaults, can be used instead of import pdb; pdb.set_trace().

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

The debugger’s prompt is (Pdb), which is the indicator that you are in debug mode:

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

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

You can also invoke pdb from the command line to debug other scripts. For example:

python -m pdb myscript.py

When invoked as a module, pdb will automatically enter post-mortem debugging if the program being debugged exits abnormally. After post-mortem debugging (or after normal exit of the program), pdb will restart the program. Automatic restarting preserves pdb’s state (such as breakpoints) and in most cases is more useful than quitting the debugger upon program’s exit.

Змінено в версії 3.2: Added the -c option to execute commands as if given in a .pdbrc file; see Команди налагоджувача.

Змінено в версії 3.7: Added the -m option to execute modules similar to the way python -m does. As with a script, the debugger will pause execution just before the first line of the module.

Typical usage to execute a statement under control of the debugger is:

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

Змінено в версії 3.13: The implementation of PEP 667 means that name assignments made via pdb will immediately affect the active scope, even when running inside an optimized scope.

Модуль визначає такі функції; кожен входить до відладчика дещо іншим способом:

pdb.run(statement, globals=None, locals=None)

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

pdb.runeval(expression, globals=None, locals=None)

Evaluate the expression (given as a string or a code object) under debugger control. When runeval() returns, it returns the value of the expression. Otherwise this function is similar to run().

pdb.runcall(function, *args, **kwds)

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

pdb.set_trace(*, header=None)

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

Змінено в версії 3.7: Лише ключовий аргумент header.

Змінено в версії 3.13: set_trace() will enter the debugger immediately, rather than on the next line of code to be executed.

pdb.post_mortem(traceback=None)

Введіть посмертне налагодження даного об’єкта traceback. Якщо traceback не надано, використовується виняткова ситуація, яка зараз обробляється (виняток має оброблятися, якщо має використовуватись типове значення).

pdb.pm()

Enter post-mortem debugging of the exception found in 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]

By default, Pdb sets a handler for the SIGINT signal (which is sent when the user presses Ctrl-C on the console) when you give a continue command. This allows you to break into the debugger again by pressing Ctrl-C. If you want Pdb not to touch the SIGINT handler, set nosigint to true.

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

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

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

Викликає подію аудиту pdb.Pdb без аргументів.

Змінено в версії 3.1: Added the skip parameter.

Змінено в версії 3.2: Added the nosigint parameter. Previously, a SIGINT handler was never set by Pdb.

Змінено в версії 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 також можуть мати префікс знаком оклику (!). Це потужний спосіб перевірити програму, яка налагоджується; можна навіть змінити змінну або викликати функцію. Коли в такому операторі виникає виняток, ім’я виключення друкується, але стан налагоджувача не змінюється.

Змінено в версії 3.13: Expressions/Statements whose prefix is a pdb command are now correctly identified and executed.

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

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

To set a temporary global variable, use a convenience variable. A convenience variable is a variable whose name starts with $. For example, $foo = 1 sets a global variable $foo which you can use in the debugger session. The convenience variables are cleared when the program resumes execution so it’s less likely to interfere with your program compared to using normal variables like foo = 1.

There are three preset convenience variables:

• $_frame: the current frame you are debugging

• $_retval: the return value if the frame is returning

• $_exception: the exception if the frame is raising an exception

Added in version 3.12: Added the convenience variable feature.

If a file .pdbrc exists in the user’s home directory or in the current directory, it is read with 'utf-8' encoding and executed as if it had been typed at the debugger prompt, with the exception that empty lines and lines starting with # are ignored. This is particularly useful for aliases. If both files exist, the one in the home directory is read first and aliases defined there can be overridden by the local file.

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

Змінено в версії 3.11: .pdbrc is now read with 'utf-8' encoding. Previously, it was read with the system locale encoding.

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.

With a function argument, set a break at the first executable statement within that function. function can be any expression that evaluates to a function in the current namespace.

Якщо присутній другий аргумент, це вираз, який повинен отримати значення true перед тим, як буде враховано точку зупину.

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

Each breakpoint is assigned a number to which all the other breakpoint commands refer.

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

Тимчасова контрольна точка, яка видаляється автоматично при першому попаданні. Аргументи такі ж, як і для break.

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

За допомогою аргументу filename:lineno очистіть усі точки зупину в цьому рядку. За допомогою списку номерів точок зупину, розділених пробілами, очистіть ці точки зупину. Без суперечок очистіть усі розриви (але спочатку запитайте підтвердження).

disable bpnumber [bpnumber ...]

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

enable bpnumber [bpnumber ...]

Увімкніть вказані точки зупину.

ignore bpnumber [count]

Set the ignore count for the given breakpoint number. If count is omitted, the ignore count is set to 0. A breakpoint becomes active when the ignore count is zero. When non-zero, the count is decremented each time the breakpoint is reached and the breakpoint is not disabled and any associated condition evaluates to true.

condition bpnumber [condition]

Встановіть нову умову для точки зупину, вираз, який повинен мати значення true, перш ніж точка зупину буде виконана. Якщо умова відсутня, усі наявні умови видаляються; тобто точка зупину стає безумовною.

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

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]

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

With lineno, continue execution until a line with a number greater or equal to lineno is reached. In both cases, also stop when the current frame returns.

Змінено в версії 3.2: Дозволяє вказувати явний номер рядка.

r(eturn)

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

c(ont(inue))

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

j(ump) lineno

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

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

l(ist) [first[, last]]

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

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

Змінено в версії 3.2: Added the >> marker.

ll | longlist

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

Added in version 3.2.

a(rgs)

Print the arguments of the current function and their current values.

p expression

Evaluate expression in the current context and print its value.

Примітка

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

pp expression

Like the p command, except the value of expression is pretty-printed using the pprint module.

whatis expression

Print the type of expression.

source expression

Try to get source code of expression and display it.

Added in version 3.2.

display [expression]

Display the value of expression if it changed, each time execution stops in the current frame.

Without expression, list all display expressions for the current frame.

Примітка

Display evaluates expression and compares to the result of the previous evaluation of expression, so when the result is mutable, display may not be able to pick up the changes.

Приклад:

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

Display won’t realize lst has been changed because the result of evaluation is modified in place by lst.append(1) before being compared:

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

You can do some tricks with copy mechanism to make it work:

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

Added in version 3.2.

undisplay [expression]

Do not display expression anymore in the current frame. Without expression, clear all display expressions for the current frame.

Added in version 3.2.

interact

Start an interactive interpreter (using the code module) in a new global namespace initialised from the local and global namespaces for the current scope. Use exit() or quit() to exit the interpreter and return to the debugger.

Примітка

As interact creates a new dedicated namespace for code execution, assignments to variables will not affect the original namespaces. However, modifications to any referenced mutable objects will be reflected in the original namespaces as usual.

Added in version 3.2.

Змінено в версії 3.13: exit() and quit() can be used to exit the interact command.

Змінено в версії 3.13: interact directs its output to the debugger’s output channel rather than sys.stderr.

alias [name [command]]

Create an alias called name that executes command. The command must not be enclosed in quotes. Replaceable parameters can be indicated by %1, %2, … and %9, while %* is replaced by all the parameters. If command is omitted, the current alias for name is shown. If no arguments are given, all aliases are listed.

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

Delete the specified alias name.

! statement

Execute the (one-line) statement in the context of the current stack frame. The exclamation point can be omitted unless the first word of the statement resembles a debugger command, e.g.:

(Pdb) ! n=42
(Pdb)

To set a global variable, you can prefix the assignment command with a global statement on the same line, e.g.:

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

run [args ...]

restart [args ...]

Restart the debugged Python program. If args is supplied, it is split with shlex and the result is used as the new sys.argv. History, breakpoints, actions and debugger options are preserved. restart is an alias for run.

q(uit)

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

debug code

Enter a recursive debugger that steps through code (which is an arbitrary expression or statement to be executed in the current environment).

retval

Print the return value for the last return of the current function.

exceptions [excnumber]

List or jump between chained exceptions.

When using pdb.pm() or Pdb.post_mortem(...) with a chained exception instead of a traceback, it allows the user to move between the chained exceptions using exceptions command to list exceptions, and exception <number> to switch to that exception.

Приклад:

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

calling pdb.pm() will allow to move between exceptions:

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

Added in version 3.13.

Виноски

[1]

Чи вважається, що фрейм походить із певного модуля, визначається __name__ у глобальних параметрах фрейму.