Отладка скрипта в Python: короткая инструкция с pdb

В конце этой инструкции вы сможете остановить любой Python-скрипт на выбранной строке, посмотреть значения переменных в этот момент и пройти код шаг за шагом. Всё это без единого print и без установки сторонних пакетов — отладчик pdb входит в стандартную библиотеку. На то, чтобы разобраться и попробовать на своём коде, уйдёт около 20 минут. Всё написано для Python 3.7 и новее.

Что нужно иметь до начала

• Python 3.7 или новее. Проверьте командой python --version или python3 --version в терминале — должна вывестись строка вида Python 3.11.6.
• Любой скрипт .py, который запускается из терминала. Если запускаете код в Jupyter — там свой механизм, эта инструкция про обычные скрипты.
• Доступ к терминалу (командной строке). Отладка идёт в интерактивном режиме, поэтому запускать нужно именно оттуда, а не двойным кликом.

Встроенная команда breakpoint(), которой мы будем пользоваться, появилась в Python 3.7. На более старых версиях вместо неё пишут import pdb; pdb.set_trace() — результат тот же.

Пошагово: ставим точку останова и смотрим переменные

Возьмём скрипт с ошибкой в логике. Функция считает среднее, но делит на неправильное число, и результат выходит не тот, что ожидали.

# average.py — Python 3.7+
def average(numbers):
    total = 0
    for value in numbers:
        total += value
    # где-то тут ошибка: делим не на то
    result = total / (len(numbers) - 1)
    return result


data = [10, 20, 30, 40]
print("Среднее:", average(data))

1. Поставьте точку останова. Впишите вызов breakpoint() на той строке, где хотите остановиться — например, перед вычислением result:

   def average(numbers):
       total = 0
       for value in numbers:
           total += value
       breakpoint()  # выполнение остановится здесь
       result = total / (len(numbers) - 1)
       return result
   

   Как понять, что получилось: при запуске скрипта в терминале вместо привычного вывода появится приглашение (Pdb) — это значит, отладчик перехватил управление.

2. Запустите скрипт из терминала:

   python average.py

   Выполнение дойдёт до breakpoint() и встанет. Вы увидите строку с номером и приглашение (Pdb).

3. Посмотрите значения переменных. Введите имя переменной и нажмите Enter — отладчик покажет её значение прямо сейчас:

   (Pdb) total
   100
   (Pdb) len(numbers)
   4
   

   Как понять, что получилось: вы увидите total равным 100, а len(numbers) равным 4. Значит, делить надо на 4, а не на 4 - 1. Ошибка найдена.

4. Проверьте выражение, не меняя код. В (Pdb) можно посчитать что угодно:

   (Pdb) total / len(numbers)
   25.0
   (Pdb) total / (len(numbers) - 1)
   33.333333333333336
   

   Видно, что правильный ответ 25, а текущая формула даёт 33.3. Это подтверждает диагноз.

5. Продолжите выполнение или выйдите. Команда c (continue) досчитает скрипт до конца или до следующего breakpoint(). Команда q (quit) прервёт выполнение и вернёт в терминал:

   (Pdb) c
   Среднее: 33.333333333333336
   

   После этого исправьте формулу на total / len(numbers) и уберите breakpoint().

Точка останова, поставленная руками, — это не грязь в коде, это черновик. Плохо не то, что вы вписали breakpoint, а то, что забыли его убрать перед коммитом.

Проход по коду по шагам

Иногда непонятно не значение переменной, а сам ход выполнения: какая ветка сработала, зашли ли в цикл, вызвалась ли нужная функция. Для этого в (Pdb) есть команды перемещения.

Одна оговорка про p. Если у вас есть переменная с именем n, s или c, простой ввод имени не сработает — pdb поймёт его как команду перемещения. В этом случае пишите p n, чтобы явно попросить напечатать значение.

Отладка при падении с ошибкой

Если скрипт не «считает не то», а падает с трейсбеком, точку останова ставить необязательно. Запустите скрипт так, чтобы pdb перехватил управление в момент падения:

python -m pdb average.py

При такой команде отладчик стартует сразу. Введите c, чтобы выполнение шло как обычно. Когда возникнет необработанное исключение, pdb остановится на строке падения — и вы сможете посмотреть переменные в момент аварии командой p имя и стек командой w. Это удобнее, чем читать трейсбек и гадать, какими были значения.

Если не получилось

• NameError: name 'breakpoint' is not defined — у вас Python старше 3.7. Замените breakpoint() на две команды: import pdb; pdb.set_trace().
• Приглашение (Pdb) не появилось, скрипт просто отработал. Скорее всего, выполнение не дошло до строки с breakpoint() — например, она внутри функции, которую не вызвали, или внутри ветки if, которая не сработала. Поставьте точку останова выше по коду и запустите снова.
• Ввод переменной выдаёт *** SyntaxError или ведёт себя как команда. Имя переменной совпало с командой pdb (n, s, l, c). Используйте p имя_переменной.
• Приглашение появилось, но ничего не набирается / нет реакции на Enter. Вы запустили скрипт не из терминала (двойной клик, кнопка «Run» без интерактивной консоли). У pdb нет ввода. Запускайте через python имя.py в терминале.
• Забыли, где остановились. Введите l — покажет код вокруг текущей строки, а стрелка укажет на неё.

Что дальше

Когда привыкнете к pdb, посмотрите на встроенный отладчик вашего редактора. В VS Code и PyCharm точки останова ставятся кликом на полях слева, а значения переменных видны в отдельной панели без набора команд — по сути то же самое, но нагляднее. Логика одна: остановиться, посмотреть, пройти по шагам.

Ещё один шаг — научиться ставить условную точку останова, которая срабатывает не всегда, а только когда, например, переменная равна нужному значению. В pdb это делается командой break с условием; синтаксис смотрите в разделе документации про pdb. Это экономит время, когда цикл прокручивается тысячу раз, а сбой случается только на одной итерации.