Редактирование кода Python
Область применения:
Visual Studio Visual Studio 
для Mac Visual Studio Code
Так как при разработке вы много работаете в редакторе кода, поддержка Python в Visual Studio предоставляет соответствующие функции для повышения продуктивности этой работы. К ним относятся выделение синтаксиса IntelliSense, автозавершение, справка по сигнатурам, переопределения методов, а также поиск и навигация.
Редактор также интегрируется с интерактивным окном в Visual Studio, упрощая обмен кодом между ними. Подробные сведения см. в разделах Учебник, шаг 3. Использование интерактивного окна REPL и Использование интерактивного окна. Команда "Отправить в интерактивное окно".
Общие сведения о редактировании кода в Visual Studio см. в статье Возможности редактора кода. Ознакомьтесь также со статьей Структура, чтобы узнать, как сконцентрироваться на определенных разделах кода.
Кроме того, с помощью обозревателя объектов Visual Studio (Вид>Другие окна>Обозреватель объектов или клавиши CTRL+W>J) вы можете проверять классы Python, определенные в каждом модуле, и функции, определенные в этих классах.
IntelliSense
Технология IntelliSense предоставляет следующие возможности: автозавершения, справка по сигнатурам, вывод кратких сведений и цветовая маркировка синтаксиса. Visual Studio 2017 версии 15.7 и более поздней также поддерживает подсказки по типам.
Для улучшения производительности функция IntelliSense в Visual Studio 2017 версии 15.5 и более ранних учитывает базу данных завершения, которая создается для каждого окружения Python в проекте. После добавления, удаления или обновления пакетов может потребоваться обновить базы данных. Их состояние отображается в окне Окружения Python (элемент того же уровня, что и обозреватель решений) на вкладке IntelliSense (см. дополнительные сведения об окне "Окружения").
Visual Studio 2017 версии 15.6 и более поздних разными способами предоставляет функцию завершения IntelliSense, которая не зависит от базы данных.
Автозавершения
Автозавершения отображаются как операторы, идентификаторы и другие атрибуты, которые можно ввести в текущее расположение в редакторе. Автозавершения, отображаемые в списке, основываются на контексте, а также фильтруются для пропуска неправильных или ненужных параметров. Они часто инициируются при вводе различных инструкций (например, import) и операторов (включая точку). Но их также можно отобразить в любое время, нажав клавиши CTRL+J>ПРОБЕЛ.
В открытом списке автозавершений можно выполнить поиск необходимого автозавершения с помощью клавиш со стрелками, мыши или путем ввода. Чем больше букв вы вводите, чем точнее фильтруется список для отображения возможных автозавершений. Кроме того, можно использовать следующие ярлыки:
- ввод букв, которые находятся не в начале имени, например parse для поиска argparse;
- ввод букв, которые находятся только в начале слов, например abc для поиска AbstractBaseClass или air для поиска as_integer_ratio;
- пропуск букв, например b64 для поиска base64.
Некоторые примеры:
Завершения элементов автоматически отображаются при вводе точки после переменной или значения. Вместе с ними отображаются методы и атрибуты потенциальных типов. Если переменная может быть нескольких типов, в списке содержатся все возможные варианты для всех типов с дополнительными сведениями для указания типов, поддерживающих каждое автозавершение. Если автозавершение поддерживается всеми возможными типами, оно отображается без заметки.
Элементы, которые начинаются и заканчиваются двумя символами подчеркивания, не отображаются по умолчанию. В общем случае к таким элементам не следует обращаться напрямую. Если же элемент нужен, введя два начальных символа подчеркивания, можно добавить эти завершения в список:
Операторы import и from ... import отображают список модулей, которые можно импортировать. При использовании from ... import список содержит элементы, которые можно импортировать из указанного модуля.
При использовании операторов raise и except отображаются списки классов, которые могут быть типами ошибок. При этом необязательно выводятся все определяемые пользователем исключения, но с их помощью можно быстро найти подходящие встроенные исключения.
При вводе символа @ запускается декоратор и отображаются потенциальные декораторы. Многие из этих элементов невозможно использовать в качестве декораторов. Чтобы определить, какие именно из них следует использовать, обратитесь к документации по библиотеке.
Совет
Вы можете настроить поведение автозавершений, выбрав Инструменты>Параметры>Текстовый редактор>Python>Дополнительно. Параметр Фильтрация списка по поисковой строке позволяет применить фильтрацию предложений автозавершения при вводе (флажок установлен по умолчанию), а при выборе параметра Завершение членов отображает пересечение членов отображаются только те автозавершения, которые поддерживают все возможные типы (флажок снят по умолчанию). См. раздел Параметры. Результаты завершения.
Подсказки по типам
Visual Studio 2017 версии 15.7 и более поздней.
Подсказки по типам в Python 3.5+ (PEP 484 (python.org) — это синтаксис аннотаций для функций и классов, который указывает на типы аргументов, возвращаемых значений и атрибутов класса. IntelliSense отображает подсказки по типам при наведении курсора на вызовы функций, аргументы и переменные с этими аннотациями.
В следующем примере класс Vector объявлен как List[float], и функция scale содержит подсказки по типам для аргументов и возвращаемого значения. При наведении указателя на вызов этой функции отображаются следующие подсказки по типам:
В следующем примере можно увидеть, как аннотированные атрибуты класса Employee отображаются во всплывающем окне завершения IntelliSense для атрибута:
Полезно проверять подсказки по типам на протяжении проекта, поскольку ошибки обычно не возникают до выполнения. Для этой цели Visual Studio интегрирует стандартное средство MyPy через команду контекстного меню Python>Run Mypy в обозревателе решений:
При запуске команды отображается запрос на установку пакета mypy при необходимости. Затем Visual Studio запускает mypy для проверки подсказок по типам в каждом файле Python в проекте. Ошибки отображаются в окне Список ошибок в Visual Studio. При выборе элемента в окне вы перейдете к соответствующей строке в коде.
Приведем простой пример. Следующее определение функции содержит подсказку по типам, указывая на то, что аргумент input имеет тип str, тогда как вызов этой функции пытается передать целое число:
def commas_to_colons(input: str):
items = input.split(',')
items = [x.strip() for x in items]
return ':'.join(items)
commas_to_colons(1)
Использование команды Run Mypy в этом коде вызывает следующую ошибку:
Совет
В версиях Python, предшествующих 3.5, в Visual Studio также отображаются подсказки по типам, которые вы предоставляете через файлы-заглушки (.pyi). Файлы заглушки можно использовать всякий раз, когда вы не хотите включать подсказки по типам в код напрямую или необходимо создать подсказки по типам для библиотеки, которая не использует их напрямую. Дополнительные сведения см. в разделе Создание заглушек для модулей Python на вики-сайте проекта mypy.
Visual Studio содержит набор пакетов файлов Typeshed для Python 2 и 3, поэтому нет необходимости скачивать их отдельно. Но если вы хотите использовать другой набор файлов, можно указать путь в меню Средства>Параметры>Python>Языковой сервер. См. статью Параметры для Python в Visual Studio.
В настоящее время Visual Studio не поддерживает подсказки по типам в комментариях.
Справка по сигнатурам
Во время написания кода, вызывающего функцию, при вводе открывающейся скобки ( отображается справка по сигнатурам, а также доступные сведения о параметрах и документации. Ее также можно отобразить внутри вызова функции, нажав клавиши CTRL+SHIFT+ПРОБЕЛ. Хотя отображаемые сведения определяются строками документации в исходном коде функции, они содержат любые значения по умолчанию.
Совет
Чтобы отключить справку по сигнатурам, выберите Инструменты>Параметры>Текстовый редактор>Python>Общие и снимите флажок Завершение операторов>Сведения о параметрах.
Вывод кратких сведений
При наведении указателя мыши на идентификатор отображается подсказка. В зависимости от идентификатора в кратких сведениях могут отображаться потенциальные значения или типы, доступная документация, возвращаемые типы и расположения определений:
Цветовая маркировка синтаксиса
Цветовая маркировка синтаксиса — это функция, которая использует сведения, основанные на анализе кода, для выделения цветом переменных, операторов и других частей кода. Например, переменные, которые относятся к модулям или классам, могут выделяться другим цветом, нежели функции и остальные значения, а имена параметров могут отличаться цветом от локальных или глобальных переменных. (По умолчанию функции не выделяются полужирным шрифтом.)
Чтобы настроить цвета, выберите Инструменты>Параметры>Среда>Шрифты и цвета и измените записи Python в списке Отображение элементов.
Совет
Чтобы отключить цветовую маркировку синтаксиса, выберите Инструменты>Параметры>Текстовый редактор>Python>Дополнительно и снимите флажок Разные параметры>Имена цветов по типам. См. раздел Параметры. Прочие параметры.
Фрагменты кода
Фрагменты кода — это фрагменты кода, которые можно вставить в файлы, введя ярлык и нажав клавишу TAB, или с помощью команды Edit>IntelliSense>Insert Snippet and Surround With, выбрав Python, а затем выберите нужный фрагмент кода.
Например, class является ярлыком для фрагмента кода, который вставляет определение класса. Вот фрагмент кода, который отображается в списке автозавершения при вводе class:
Если нажать клавишу TAB, будет создана остальная часть класса. Можно ввести имя и список базовых классов, перемещаясь между выделенными полями с помощью клавиши TAB, а затем нажав клавишу ВВОД, чтобы начать ввод текста.
Команды меню
При использовании команды меню Правка>IntelliSense>Вставить фрагмент кода сначала выберите Python, а затем — фрагмент кода:
Команда Правка>IntelliSense>Разместить во фрагменте точно так же помещает текущий выделенный фрагмент в текстовый редактор внутри выбранного структурного элемента. Предположим, у вас есть небольшой фрагмент кода:
sum = 0
for x in range(1, 100):
sum = sum + x
Если выбрать этот код и команду Разместить во фрагменте, откроется список доступных фрагментов. Если выбрать def в списке, выбранный код будет помещен в определение функции. Вы сможете переходить между выделенным именем функции имя и аргументами с помощью клавиши TAB:
Просмотр доступных фрагментов кода
Доступные фрагменты кода можно просмотреть в диспетчере фрагментов кода. Чтобы открыть его, выберите пункт меню Инструменты>Диспетчер фрагментов кода и выберите Python в качестве языка:
Сведения о том, как создать собственные фрагменты кода, см. в статье Пошаговое руководство. Создание фрагмента кода.
Если вы написали качественный фрагмент кода, к которому вы хотите предоставить общий доступ, разместите его в репозитории и сообщите нам. Возможно, мы сможем включить его в следующий выпуск Visual Studio.
Навигация по коду
Поддержка Python в Visual Studio предоставляет несколько вариантов для быстрой навигации по коду, а также по библиотекам с доступным исходным кодом: Панель навигации, Перейти к определению, Перейти к и Найти все ссылки. Можно также использовать обозреватель объектов Visual Studio.
Панель навигации
Панель навигации отображается в верхней части каждого окна редактора и содержит двухуровневый список определений. Раскрывающийся список слева содержит определения классов и функций верхнего уровня в текущем файле. Раскрывающийся список справа отображает список определений в области, расположенной слева. При перемещении курсора в редакторе эти списки обновляются для отображения текущего контекста, при этом из них можно напрямую перейти к нужной записи.
Совет
Чтобы скрыть панель навигации, выберите Инструменты>Параметры>Текстовый редактор>Python>Общие и снимите флажок Параметры>Панель навигации.
Перейти к определению
Команда Перейти к определению позволяет быстро перейти от использования идентификатора (например, имени функции, класса или переменной) к определению в исходном коде. Ее можно вызвать, щелкнув правой кнопкой мыши идентификатор и выбрав Перейти к определению или поместив курсор внутрь этого идентификатора и нажав клавишу F12. Эта команда работает в коде и внешних библиотеках, если исходный код доступен. Если исходный код библиотеки недоступен, команда Перейти к определению переходит к соответствующему оператору import для ссылки на модуль или отображает ошибку.
Функция "Перейти к"
Команда Правка>Перейти к (CTRL+,) позволяет отобразить поле поиска в редакторе, где можно ввести любую строку и увидеть возможные совпадения в коде, определяющем функцию, класс или переменную. Она обеспечивает те же возможности, что и команда Перейти к определению, но без необходимости искать, где используется идентификатор.
Чтобы перейти к определению этого идентификатора, дважды щелкните любое имя или выберите его с помощью клавиш со стрелками и клавиши ВВОД.
Найти все ссылки
Найти все ссылки — это удобная команда для обнаружения, где используется и определен нужный идентификатор, включая операции импорта и назначения. Ее можно вызвать, щелкнув правой кнопкой мыши идентификатор и выбрав пункт Найти все ссылки или поместив курсор внутри этого идентификатора и нажав клавиши SHIFT+F12. Чтобы перейти к расположению элемента, нужно дважды щелкнуть его в списке.
