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

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

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

• Удаленная отладка Linux
• Отладка в смешанном режиме Python/C++
• Символы для отладки в смешанном режиме

Необходимые условия

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

• Python код для использования с отладчиком.

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

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

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

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

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

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

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

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

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

Укажите активную среду

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

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

Установите точки останова

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

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

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

  

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

  

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

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

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

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

  

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

  

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

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

Пошаговое выполнение кода

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

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

Command	Shortcut	Описание
Остановить	SHIFT +F5	Остановите сеанс отладки.
Перезапуск	CTRL+SHIFT+F5	Перезапустите текущий сеанс отладки.
Продолжать	F5	Запустите код, пока не достигнете следующей точки останова.
Войти в	F11	Выполните следующую инструкцию и остановите. Если следующая инструкция является вызовом функции, отладчик останавливается в первой строке вызываемой функции.
Переступить	F10	Выполните следующую инструкцию, в том числе вызов функции (выполнение всего кода) и применение любого возвращаемого значения. Эта команда позволяет легко пропускать функции, которые не нужно отлаживать.
Выход	Shift+F11	Запустите код до конца текущей функции, а затем перейдите к выражению вызова. Эта команда полезна, если не нужно отлаживать оставшуюся часть текущей функции.
Запуск до курсора	CTRL+F10	Запустите код до расположения каретки в редакторе. Эта команда позволяет легко пропустить сегмент кода, который не требуется отлаживать.
Set Next Statement (Установить следующую инструкцию)	Ctrl+Shift+F10	Измените текущую точку запуска в коде на расположение курсора. Эта команда позволяет не выполнять сегмент кода, например, когда вы знаете, что код содержит ошибку или создает нежелательный побочный эффект.
показать следующую инструкцию	Alt+Num+\	Вернитесь к следующей инструкции для выполнения в коде. Эта команда помогает найти место в коде, в котором остановлен отладчик.

Проверка и изменение значений

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

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

  

• Чтобы использовать окно Locals, выберите Debug>Windows>Locals. В этом окне отображаются все переменные, находящиеся в текущей области. Чтобы изменить значение, дважды щелкните столбец значений или введите клавишу F2 :

  

  Дополнительные сведения об использовании окна "Локальные" см. в разделе "Проверка переменных" в окнах "Авто" и "Локальные".

• Чтобы использовать Watch windows, выберите Debug>Windows>Watch>Watch 1-4. Этот параметр позволяет вводить произвольные Python выражения и просматривать результаты. Выражения пересчитываются на каждом шаге.

  

  Дополнительные сведения об использовании окна Наблюдатель см. в разделе Настройка наблюдения за переменными с окнами Наблюдатель и Быстрый просмотр.

• Чтобы проверить строковое значение, выберите «Вид» (увеличительное стекло) на правой стороне записи «Значение». Все типы str, unicode, bytes и bytearray доступны для проверки.

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

  

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

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

Если во время отладки возникает ошибка, но у вас нет обработчика исключений, отладчик прерывается в точке исключения:

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

• Чтобы просмотреть расширенное представление исключений, выберите Debug>Windows>Exception Settings.

  

  В окне "Параметры исключений " флажок рядом с исключением определяет, всегда ли отладчик прерывается при возникновении этого исключения.

• Чтобы чаще разорвать конкретное исключение, установите флажок рядом с исключением в окне "Параметры исключений ".

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

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

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

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

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

  

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

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

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

Ценность	Описание
средство запуска Standard 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.

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

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

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

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

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

Откройте окно немедленного выполнения

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

• Чтобы открыть окно Immediate, выберите Debug>Windows>Immediate. Вы также можете использовать сочетание клавиш CTRL+ALT+I.

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

Окно Python Debug Interactive предлагает богатую среду с полным набором возможностей Interactive REPL, доступных во время отладки, включая возможность написания и выполнения кода. Это окно автоматически подключается к любому процессу, запущенному в отладчике, с помощью средства запуска стандартного Python, включая процессы, подключенные через Debug>Attach to Process. Однако это окно недоступно при использовании отладки в смешанном режиме C/C++.

• Чтобы использовать окно Debug Interactive, select Debug>Windows>Python Debug Interactive (Shift+Alt+I).

  

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

Command	Описание
$continue $cont $c	Запустите программу из текущей инструкции.
$down, $d	Перемещение текущего кадра на один уровень вниз в трассировке стека.
$frame	Отображение текущего идентификатора кадра.
$frame	Переключите текущий кадр на указанный идентификатор кадра. — требуется аргумент ID< кадра>.
$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 и более ранних версий.

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

Поддержка старых версий 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 отображает ошибку, Debugger не поддерживает эту среду Python:

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

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

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

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

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

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

Important

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

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

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

1. В окне среда Python перейдите на вкладку пакеты.

2. Введите ptvsd в поле поиска и проверьте установленную версию ptvsd:

   

3. Если версия ниже 4.1.1a9 (версия, связанная с Visual Studio), выберите X справа от пакета, чтобы удалить старую версию. Visual Studio затем использует свою пакетную версию. (Вы также можете удалить из PowerShell с помощью pip uninstall ptvsd команды.)

4. Кроме того, можно обновить пакет ptvsd до новой версии, следуя инструкциям в разделе "Устранение неполадок в сценариях отладки ".

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

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

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

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

1. В окне среды Python перейдите на вкладку Пакеты.

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

   

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

   Замечание

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

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

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

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

1. Откройте командное окно в Visual Studio, выбрав View>Other Windows>Command Window.

2. Введите следующую команду:

   DebugAdapterHost.Logging /On /OutputWindow
   

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

   

4. Если Visual Studio перестает отвечать или вы не сможете получить доступ к Output окно, перезапустите Visual Studio, откройте командное окно и введите следующую команду:

   DebugAdapterHost.Logging /On
   

5. Запустите отладку, и повторно воспроизведите проблему. Журналы отладчика находятся в %temp%\DebugAdapterHostLog.txt.

Связанный контент

• Отладка в Visual Studio
• Отладка в смешанном режиме для Python/C++
• Символы для отладки в смешанном режиме