Отладка кода Python в Visual Studio

Статья
04/18/2024

Visual Studio предоставляет полный интерфейс отладки для Python. В этой статье вы узнаете, как подключить отладчик к запущенным процессам и оценить выражения в окнах "Контрольные данные" и "Интерпретация ". В отладчике можно проверить локальные переменные, использовать точки останова, инструкции in/out/over, Set Next Statement и многое другое.

Сведения об отладке для конкретного сценария см. в следующих статьях:

Необходимые компоненты

Visual Studio, установленная с поддержкой рабочих нагрузок Python. Дополнительные сведения см. в статье "Установка поддержки Python в Visual Studio".
Код Python для использования с отладчиком.

Отладка кода с проектом или без нее

Если вы хотите управлять средой и аргументами Python, сначала создайте проект для кода. Проект можно создать с помощью существующего шаблона проекта кода Python. Дополнительные сведения см. в статье "Создание проекта из существующих файлов кода Python".

Однако для отладки кода Python не требуется файл проекта или решения в Visual Studio. Чтобы выполнить отладку кода в автономном файле Python, откройте файл в Visual Studio и выберите "Начать отладку>". Visual Studio запускает скрипт с глобальной средой по умолчанию и без аргументов. После этого у вас есть полная поддержка отладки кода. Дополнительные сведения см. в описании окружений Python.

Изучение базовой отладки

Базовый рабочий процесс отладки включает параметры точек останова, пошаговое выполнение кода, проверку значений и обработку исключений. Вы можете запустить сеанс отладки, выбрав >"Отладка начать отладку" или с помощью сочетания клавиш F5. Для проекта эти действия запускают файл запуска с активной средой проекта и любыми аргументами командной строки или путями поиска, указанными для свойств проекта. Сведения о настройке свойств см. в разделе "Настройка параметров отладки проекта".

Настройка файла запуска проекта

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

Чтобы указать файл проекта в качестве файла запуска, щелкните его правой кнопкой мыши и выберите "Задать в качестве элемента запуска".

В Visual Studio 2017 версии 15.6 и более поздних версиях вы увидите оповещение, если у вас нет указанного набора файлов запуска. Более ранние версии Visual Studio могут открыть окно вывода с запущенным интерпретатором Python или окно вывода кратко открывается и закрывается.

Указание активной среды

Если вы используете файл проекта, отладчик всегда начинается с активной среды Python для проекта. Вы можете изменить текущую активную среду. Дополнительные сведения см. в разделе "Выбор среды Python" для проекта.

Если вы выполняете отладку автономного файла кода Python, Visual Studio запускает скрипт с глобальной средой по умолчанию и без аргументов.

Задание точек останова

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

Некоторые точки останова в коде Python могут быть неожиданными для тех разработчиков, которые привыкли использовать другие языки программирования. При использовании языка Python весь файл является исполняемым кодом, таким образом Python запускает файл во время загрузки для обработки определений классов верхнего уровня или функций. Если задана точка останова, то можно найти отладчик с критическим путем объявления класса. Это верное, хотя и несколько неожиданное поведение.

Чтобы задать точку останова, выберите в левом поле редактора кода или щелкните правой кнопкой мыши строку кода и выберите точку>останова вставить точку останова. Красная точка отображается на каждой строке с заданной точкой останова.
Чтобы удалить точку останова, выберите красную точку или щелкните правой кнопкой мыши строку кода и выберите точку>останова Удалить точку останова. Вы также можете отключить точку останова, выбрав красную точку и выбрав >точку останова.

Настройка условий и действий

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

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

В диалоговом окне можно добавить несколько условий и создать условные выражения с помощью кода Python. Подробные сведения об этой возможности в Visual Studio см. в разделе Условия точки останова.
Вы также можете задать действия для точки останова. Вы можете создать сообщение для входа в окно вывода и при необходимости указать, чтобы продолжить выполнение автоматически.

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

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

Пошаговое прохождение кода

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

В следующей таблице приведены следующие команды и приведены сочетания клавиш:

Команда	Ярлык	Description
Продолжить	F5	Запустите код, пока не достигнет следующей точки останова.
Шаг с заходом	F11	Выполните следующую инструкцию и остановите. Если следующая инструкция является вызовом функции, отладчик останавливается в первой строке вызываемой функции.
Шаг с обходом	F10	Выполните следующую инструкцию, в том числе вызов функции (выполнение всего кода) и применение любого возвращаемого значения. Эта команда позволяет легко пропускать функции, которые не нужно отлаживать.
Шаг с выходом	Shift+F11	Запустите код до конца текущей функции, а затем перейдите к оператору вызова. Эта команда полезна в том случае, если не требуется отладка остальной части текущей функции.
Выполнить до текущей позиции	CTRL+F10	Запустите код до расположения курсора в редакторе. Эта команда позволяет легко пропустить сегмент кода, для которого не нужно делать отладку.
Задать следующий оператор	CTRL+SHIFT+F10	Измените текущую точку выполнения в коде на расположение курсора. Эта команда позволяет полностью пропустить выполнение сегмента кода, например, если известно, что код неисправен или приводит к нежелательным побочным эффектам.
Показать следующий оператор	ALT+NUM+\	Вернитесь к следующей инструкции для выполнения в коде. Эта команда помогает найти место в коде, в котором остановлен отладчик.

Просмотр и изменение значений

При остановке выполнения кода в отладчике можно проверить и изменить значения переменных. Окно контрольных значений позволяет отслеживать отдельные переменные, а также пользовательские выражения. Дополнительные сведения см. в разделе "Проверка переменных".

Чтобы просмотреть значение с помощью функции Data Советы во время отладки, наведите указатель мыши на любую переменную в редакторе. Чтобы изменить переменную, можно выбрать следующее:
Чтобы использовать окно "Автозапуск", выберите "Отладка>Windows>Autos". Это окно содержит переменные и выражения, близкие к текущей инструкции. Чтобы изменить значение, дважды щелкните столбец значений или введите клавишу F2 :

Дополнительные сведения об использовании окна "Автозапуск" см. в разделе "Проверка переменных" в окнах "Авто" и "Локальные".
Чтобы использовать окно "Локальные" выберите "Отладка>локальных" windows.> В этом окне отображаются все переменные, находящиеся в текущей область, которые можно изменить снова:

Дополнительные сведения об использовании окна "Локальные" см. в разделе "Проверка переменных" в окнах "Авто" и "Локальные".
Чтобы использовать окна "Просмотр", выберите "Отладка>часов Windows>Watch>1-4". Этот параметр позволяет вводить произвольные выражения Python и просматривать результаты. Выражения повторно вычисляются для каждого шага:

Дополнительные сведения об использовании окна "Просмотр " см. в разделе "Настройка часов" для переменных с окнами "Контрольные и быстрые часы".
Чтобы проверить строковое значение, в правой части записи "Значение" нажмите кнопку "Вид" (увеличивающееся стекло). Все strunicodebytesтипы и bytearray типы доступны для проверки.

В раскрывающемся меню представления отображаются четыре варианта визуализации: текст, HTML, XML или JSON.

После выбора визуализации всплывающее диалоговое окно отображает неquoted строковое значение в соответствии с выбранным типом. Строку можно просмотреть с помощью оболочки и прокрутки, выделения синтаксиса и представлений дерева. Эти визуализации могут помочь в отладке проблем с длинными и сложными строками.

Просмотр исключений

Если в процессе отладки возникает ошибка, для которой нет обработчика исключений, отладчик останавливается в точке исключения.

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

Чтобы просмотреть расширенное представление исключений, выберите "Отладка>исключений Windows>" Параметры.

В окне "Исключения" Параметры поле проверка box рядом с исключением определяет, всегда ли отладчик прерывается при возникновении этого исключения.
Чтобы чаще разорвать конкретное исключение, выберите поле проверка box рядом с исключением в окне Параметры исключения.
По умолчанию большинство исключений прерываются, когда обработчик исключений не может находиться в исходном коде. Чтобы изменить такое поведение, щелкните правой кнопкой мыши любое исключение и измените значение параметра Продолжить после необработанной ошибки в коде пользователя. Чтобы реже прерывать исключение, отключите этот параметр.
Чтобы настроить исключение, которое не отображается в окне "Исключение Параметры", нажмите кнопку "Добавить" (плюс символ). Введите имя для отслеживания исключения. Имя добавляемого исключения должно соответствовать полному имени исключения.

Настройка параметров отладки проекта

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

Чтобы получить доступ к свойствам отладки для проекта, щелкните правой кнопкой мыши проект Python в Обозреватель решений, выберите "Свойства" и перейдите на вкладку "Отладка".

В следующих разделах описаны определенные свойства.

Определение поведения запуска

В следующей таблице перечислены возможные значения свойства режима запуска. Это свойство позволяет определить поведение запуска для отладчика.

значение	Описание
Стандартное средство запуска Python	Используйте код отладки, написанный в переносимом Python, совместимом с CPython, IronPython и вариантами, такими как Stackless Python. Этот параметр обеспечивает лучший способ отладки чистого кода Python. При присоединении к работающему `python.exe` процессу используется средство запуска, указанное в этом свойстве. Этот средство запуска также предоставляет отладку в смешанном режиме для CPython, что позволяет легко выполнять переход между кодом C/C++ и кодом Python.
Веб-средство запуска	Запустите браузер по умолчанию при запуске и включите отладку шаблонов. Дополнительные сведения см. в разделе отладки веб-шаблона.
Веб-средство запуска Django	Реализуйте идентичное поведение свойству веб-средства запуска, но для среды Django. Используйте этот параметр только для целей обратной совместимости.
Средство запуска IronPython (.NET)	Используйте отладчик .NET, который работает только с IronPython, но позволяет выполнять шаг между любым языковым проектом .NET, включая C# и Visual Basic. Этот средство запуска используется при присоединении к работающему процессу .NET, в котором размещается IronPython.

Определение поведения выполнения

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

Свойство	Description
Пути поиска	Укажите пути поиска файлов и папок Visual Studio, которые используются для проекта. Эти значения соответствуют элементам, отображаемым в узле пути поиска проекта в Обозреватель решений. Хотя в этом диалоговом окне можно указать пути поиска, проще использовать Обозреватель решений, где можно просматривать папки и автоматически преобразовывать пути в относительную форму.
Аргументы скрипта	Определите аргументы для добавления в команду Visual Studio, которую использует для запуска скрипта, и отображаются после имени файла скрипта. Первый элемент, указанный в значении, доступен для скрипта как `sys.argv[1]`, второй как `sys.argv[2]`и т. д.
Аргументы интерпретатора	Перечислите аргументы для добавления в командную строку средства запуска перед именем скрипта. Распространенные аргументы — `-W ...` управлять предупреждениями, `-O` слегка оптимизировать программу и `-u` использовать небуферированные операции ввода-вывода. Пользователи IronPython могут использовать это поле для передачи параметров `-X`, таких как `-X:Frames` или `-X:MTA`.
Путь к интерпретатору	Определите путь интерпретатора для переопределения пути, связанного с текущей средой. Это значение может быть полезно для запуска скрипта с нестандартным интерпретатором.
Переменные среды	Используйте это свойство для добавления записей формы `<NAME>=\<VALUE>`. Visual Studio применяет это значение свойства последнее, на вершине всех существующих глобальных переменных среды и после `PYTHONPATH` установки в соответствии с параметром пути поиска. В результате этот параметр можно использовать для ручного переопределения любой из этих других переменных.

Работа с интерактивными окнами

Во время сеанса отладки можно использовать два интерактивных окна: стандартное окно "Интерпретация Visual Studio" и интерактивноеокно отладки Python.

Открытие окна Интерпретации

Стандартное окно интерпретации Visual Studio можно использовать для быстрого вычисления выражений Python и проверки или назначения переменных в работающей программе. Дополнительные сведения см. в статье Окно интерпретации.

Чтобы открыть окно интерпретации, выберите "Отладка>Windows>Интерпретация". Вы также можете использовать сочетание клавиш CTRL+ALT+I.

Открытие интерактивного окна отладки

Интерактивное окно отладки Python предоставляет богатую среду с полным интерактивным интерфейсом REPL, доступным при отладке, включая написание и выполнение кода. Это окно автоматически подключается к любому процессу, запущенному в отладчике, с помощью средства запуска Python уровня "Стандартный", включая процессы, подключенные через подключение отладки>к процессу. Однако это окно недоступно при использовании отладки в смешанном режиме C/C++.

Чтобы использовать интерактивное окно отладки, выберите "Отладка Windows Python Debug>>Interactive" (SHIFT+ALT+I).

Интерактивное окно отладки поддерживает специальные мета-команды в дополнение к стандартным командам REPL, как описано в следующей таблице:

Команда	Description
`$continue`, , `$cont$c`	Запустите программу из текущей инструкции.
`$down`, `$d`	Переместите текущий кадр на один уровень вниз в трассировке стека.
`$frame`	Отображение текущего идентификатора кадра.
`$frame`	Переключите текущий кадр на указанный идентификатор кадра. — требуется аргумент идентификатора кадра<.>
`$load`	Загрузите команды из файла и выполняется до завершения.
`$proc`	Отображение идентификатора текущего процесса.
`$proc`	Переключите текущий процесс на указанный идентификатор процесса. — требуется аргумент идентификатора <> процесса.
`$procs`	Перечислить процессы, которые в настоящее время отлаживаются.
`$stepin`, , `$step$s`	По возможности перейдите к следующему вызову функции.
`$stepout`, , `$return$r`	Выход из текущей функции.
`$stepover`, , `$until$unt`	Выполните шаг над следующим вызовом функции.
`$thread`	Отображение текущего идентификатора потока.
`$thread`	Переключите текущий поток на указанный идентификатор потока. — требуется аргумент идентификатора <> потока.
`$threads`	Перечислить потоки, которые в настоящее время отлаживаются.
`$up`, `$u`	Перемещение текущего кадра на один уровень вверх в трассировке стека.
`$where`, , `$w$bt`	Вывод списка кадров для текущего потока.

Стандартные окна отладчика, такие как окна процессов, потоков и стека вызовов, не синхронизируются с интерактивным окном отладки. Если изменить активный процесс, поток или кадр в интерактивном окне отладки, другие окна отладчика не затрагиваются. Аналогичным образом, изменение активного процесса, потока или кадра в других окнах отладки не влияет на интерактивное окно отладки.

Использование отладчика предыдущих версий

В зависимости от конфигурации среды может потребоваться использовать отладчик прежних версий:

Visual Studio 2017 версии 15.7 и более ранних версий с Python 2.6, 3.1 до 3.4 или IronPython
Visual Studio 2019 версии 16.5 и более поздних версий с Python 2.6, 3.1 до 3.4 или IronPython
ptvsd 3.x и более ранних версий 4.x

Устаревший отладчик используется по умолчанию в Visual Studio 2017 версии 15.7 и более ранних версиях.

Чтобы использовать устаревший отладчик, выберите "Параметры инструментов>", разверните параметры отладки Python>и выберите параметр "Использовать устаревший отладчик".

Поддержка старых версий Visual Studio или Python

Visual Studio 2017 версии 15.8 и более поздних версий использует отладчик на основе PTVSD версии 4.1 и более поздних версий. Visual Studio 2019 версии 16.5 и более поздних версий использует отладчик на основе debugpy. Эти две версии отладчика совместимы с Python 2.7 или Python 3.5 и более поздними версиями.

Если вы используете одну из этих версий Visual Studio, но вы используете Python 2.6, 3.1 до 3.4 или IronPython, Visual Studio показывает ошибку, отладчик не поддерживает эту среду Python:

Когда Visual Studio сообщает об этой ошибке среды, необходимо использовать отладчик прежних версий.

Поддержка старых версий ptvsd

Если вы используете более раннюю версию ptvsd в текущей среде (например, более раннюю версию 4.0.x или версию 3.x, необходимую для удаленной отладки), Visual Studio может отобразить ошибку или предупреждение.

Если в вашей среде используется ptvsd 3.x, Visual Studio отображает ошибку, пакет отладчика не удалось загрузить:

Предупреждение, пакет отладчика устарел, отображается при использовании более ранней версии ptvsd версии 4.x:

Когда Visual Studio сообщает об ошибках среды, необходимо использовать отладчик прежних версий.

Внимание

Хотя вы можете игнорировать предупреждение для некоторых версий ptvsd, Visual Studio может работать неправильно.

Управление установкой ptvsd

Выполните следующие действия, чтобы управлять установкой ptvsd:

В окне "Среды Python" перейдите на вкладку "Пакеты".
Введите ptvsd в поле поиска и проверьте установленную версию ptvsd:
Если версия ниже, чем 4.1.1a9 (версия в составе Visual Studio), нажмите X справа от пакета, чтобы удалить старую версию. Затем Visual Studio будет использовать версию, входящую в комплект. (Вы также можете удалить из PowerShell с помощью pip uninstall ptvsd команды.)
Кроме того, можно обновить пакет ptvsd до новой версии, следуя инструкциям в разделе "Устранение неполадок в сценариях отладки ".

Устранение неполадок с сценариями отладки

В следующих сценариях описаны другие варианты устранения неполадок для конфигурации отладки.

Обновление ptvsd для Visual Studio 2019

Если у вас возникли проблемы с отладчиком в Visual Studio 2019 версии 16.4 и более ранних версий, сначала обновите версию отладчика следующим образом:

В окне "Среды Python" перейдите на вкладку "Пакеты".
Введите ptvsd --upgrade в поле поиска, а затем выберите команду Run: pip install ptvsd --upgrade. (Также можно использовать эту из PowerShell.)

Если проблемы сохраняются, отправьте проблему в репозиторий GitHub PTVS.

Примечание.

В Visual Studio 2019 версии 16.5 и последующих отладчик debugpy является частью рабочей нагрузки Visual Studio Python и обновляется вместе с Visual Studio.

Включение ведения журнала отладчика

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

Следующие шаги позволяют включить отладку в текущем сеансе Visual Studio.

Откройте командное окно в Visual Studio, выбрав "Просмотреть>другое командное окно Windows>".
Введите следующую команду:
```
DebugAdapterHost.Logging /On /OutputWindow
```
Запустите отладку и выполните действия, необходимые для воспроизведения проблемы. В это время журналы отладки отображаются в окне Выходные данные в разделе Журнал размещения адаптеров отладки. Затем вы можете скопировать журналы из этого окна и вставить их в проблему GitHub, электронную почту и т. д.
Если Visual Studio перестает отвечать на запросы или вам не удается получить доступ к окну выходных данных, перезапустите Visual Studio, откройте командное окно и введите следующую команду:
```
DebugAdapterHost.Logging /On
```
Начните отладку и снова воспроизведите проблему. Журналы отладчика находятся в %temp%\DebugAdapterHostLog.txt.

Отладка кода Python в Visual Studio

Необходимые компоненты

Отладка кода с проектом или без нее