# `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, commands=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. The commands argument, if given, is a list of commands to execute when the debugger starts.

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

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

  Added in version 3.14: The commands argument.

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, mode=None)

  `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 із файлової системи.

  The mode argument specifies how the debugger was invoked. It impacts the workings of some debugger commands. Valid values are `'inline'` (used by the breakpoint() builtin), `'cli'` (used by the command line invocation) or `None` (for backwards compatible behaviour, as before the mode argument was added).

  Приклад виклику для ввімкнення трасування за допомогою 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.

  Added in version 3.14: Added the mode argument.

  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) [count]

  Print a stack trace, with the most recent frame at the bottom. if count is 0, print the current frame entry. If count is negative, print the least recent - count frames. If count is positive, print the most recent count frames. An arrow (`>`) indicates the current frame, which determines the context of most commands.

  Змінено в версії 3.14: count argument is added.

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`. Acceptable 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` або будь-якою іншою командою, яка відновлює виконання.

  Specifying any command resuming execution (currently `continue`, `step`, `next`, `return`, `until`, `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 the list of commands contains the `silent` command, or a command that resumes execution, then the breakpoint message containing information about the frame is not displayed.

  Змінено в версії 3.14: Frame information will not be displayed if a command that resumes execution is present in the command list.

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`.

  Змінено в версії 3.14: `run` and `restart` commands are disabled when the debugger is invoked in `'inline'` mode.

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__` у глобальних параметрах фрейму.