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

The debugger’s prompt is `(Pdb)`. Typical usage to run a program under control of the debugger is:

    >>> import pdb
    >>> import mymodule
    >>> pdb.run('mymodule.test()')
    > <string>(0)?()
    (Pdb) continue
    > <string>(1)?()
    (Pdb) continue
    NameError: 'spam'
    > <string>(1)?()
    (Pdb)

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

`pdb.py` can also be invoked as a script to debug other scripts. For example:

    python -m pdb myscript.py

When invoked as a script, 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: `pdb.py` now accepts a `-c` option that executes commands as if given in a `.pdbrc` file, see Команди налагоджувача.

Нове в версії 3.7: `pdb.py` now accepts a `-m` option that 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.

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

    import pdb; pdb.set_trace()

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

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

Типове використання для перевірки збійної програми:

    >>> import pdb
    >>> import mymodule
    >>> mymodule.test()
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
      File "./mymodule.py", line 4, in test
        test2()
      File "./mymodule.py", line 3, in test2
        print(spam)
    NameError: spam
    >>> pdb.pm()
    > ./mymodule.py(3)test2()
    -> print(spam)
    (Pdb)

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

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

`pdb.``post_mortem`(traceback=None)

  Enter post-mortem debugging of the given traceback object. If no traceback is given, it uses the one of the exception that is currently being handled (an exception must be being handled if the default is to be used).

`pdb.``pm`()

  Enter post-mortem debugging of the traceback found in `sys.last_traceback`.

Функції `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: The skip argument.

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

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

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

If a file `.pdbrc` exists in the user’s home directory or in the current directory, it is read in and executed as if it had been typed at the debugger prompt. 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`. Раніше ці команди не діяли.

`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 there in the current file. With a function argument, set a break at the first executable statement within that function. The line number may be prefixed with a filename and a colon, to specify a breakpoint in another file (probably one that hasn’t been loaded yet). The file is searched on `sys.path`. Note that each breakpoint is assigned a number to which all the other breakpoint commands refer.

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

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

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

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

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

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

`disable``[bpnumber ...]`

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

`enable``[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: The `>>` marker.

`ll``| longlist`

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

  Нове в версії 3.2.

`a(rgs)`

  Print the argument list of the current function.

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

  Нове в версії 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.

  Нове в версії 3.2.

`undisplay``[expression]`

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

  Нове в версії 3.2.

`interact`

  Start an interactive interpreter (using the `code` module) whose global namespace contains all the (global and local) names found in the current scope.

  Нове в версії 3.2.

`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 so on, 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. 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 a function.

Виноски

1

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