Проекты Python в Visual Studio Python projects in Visual Studio

Приложения Python обычно определяются только с помощью файлов и папок, но такая структура может усложнить работу, так как приложения увеличиваются в размере и могут содержать автоматически сгенерированные файлы, JavaScript для веб-приложений и т. д. Python applications are typically defined using only folders and files, but this structure can become complex as applications become larger and perhaps involve auto-generated files, JavaScript for web applications, and so on. Проект Visual Studio помогает управлять этими сложными моментами. A Visual Studio project helps manage this complexity. Проект (файл .pyproj) определяет все исходные файлы и файлы содержимого, связанные с проектом, содержит сведения о сборке каждого файла, хранит информацию для интеграции с системами управления версиями и помогает упорядочить приложение в виде логических компонентов. The project (a .pyproj file) identifies all the source and content files associated with your project, contains build information for each file, maintains the information to integrate with source-control systems, and helps you organize your application into logical components.

Кроме того, проекты всегда управляются в решении Visual Studio, которое может содержать любое число проектов с возможностью ссылаться друг на друга. In addition, projects are always managed within a Visual Studio solution, which can contain any number of projects that might reference one another. Например, проект Python может ссылаться на проект C++, который реализует модуль расширения. For example, a Python project can reference a C++ project that implements an extension module. Благодаря этой связи Visual Studio автоматически создает проект C++ (при необходимости), когда вы запускаете отладку проекта Python. With this relationship, Visual Studio automatically builds the C++ project (if necessary) when you start debugging the Python project. (Общие сведения см. в статье Решения и проекты в Visual Studio.) (For a general discussion, see Solutions and projects in Visual Studio.)

Visual Studio предоставляет множество шаблонов проектов Python, позволяющих быстро настроить несколько структур приложений, а также шаблон для создания проекта из существующего дерева папок и шаблон для создания пустого проекта. Visual Studio provides a variety of Python project templates to quickly set up a number of application structures, including a template to create a project from an existing folder tree and a template to create a clean, empty project. Список шаблонов см. в разделе Шаблоны проектов. See Project templates for an index.

В Visual Studio 2019 можно открыть папку с кодом Python и выполнить этот код, не создавая проект Visual Studio и файлы решения. Visual Studio 2019 supports opening a folder containing Python code and running that code without creating Visual Studio project and solution files. Дополнительные сведения см. в разделе Краткое руководство. Открытие и выполнение кода Python в папке. For more information, see Quickstart: Open and run Python code in a folder. Но файл проекта имеет ряд важных преимуществ, которые мы описали в этой статье. There are, however, benefits to using a project file, as explained in this section.

Все версии Visual Studio нормально работают с кодом Python даже без проекта. Without a project, all versions of Visual Studio work well with Python code. Например, можно открыть сам файл Python и выполнить автозавершение и отладку, а также использовать функцию IntellSense. Для этого щелкните правой кнопкой мыши в редакторе и выберите пункт Запуск с отладкой. For example, you can open a Python file by itself and enjoy auto-complete, IntelliSense, and debugging (by right-clicking in the editor and selecting Start with Debugging). Такой код всегда использует глобальное окружение по умолчанию, однако при работе могут возникать неверные завершения или ошибки, если код предназначен для другого окружения. Because such code always uses the default global environment, however, you may see incorrect completions or errors if the code is meant for a different environment. Кроме того, Visual Studio анализирует все файлы и пакеты в папке, из которой открыт один файл, что может значительно расходовать время ЦП. Furthermore, Visual Studio analyzes all files and packages in the folder from which the single file is opened, which could consume considerable CPU time.

Проект Visual Studio можно создать из существующего кода, как описано в разделе Создание проекта из существующих файлов. It’s a simple matter to create a Visual Studio project from existing code, as described in Create a project from existing files.

Подробный обзор. Использование системы управления версиями в проектах Python (8 мин 55 с, youtube.com). Deep Dive: Use source control with Python projects (youtube.com, 8m 55s).

Добавление файлов, назначение файла запуска и настройка сред Add files, assign a startup file, and set environments

При разработке приложения обычно требуется добавить в проект новые файлы различных типов. As you develop your application, you typically need to add new files of different types to the project. Чтобы это сделать, щелкните правой кнопкой мыши проект, выберите Добавить > Существующий элемент и перейдите к нужному файлу. Можно также выбрать Добавить > Новый элемент. Появится диалоговое окно с различными шаблонами элементов. Adding such files is done by right-clicking the project and selecting Add > Existing Item with which you browse for a file to add, or Add > New Item, which brings up a dialog with a variety of item templates. Как описано в справочнике по шаблонам элементов, доступны такие варианты: пустые файлы Python, класс Python, модульный тест и различные файлы, связанные с веб-приложениями. As described on the item templates reference, options include empty Python files, a Python class, a unit test, and various files related to web applications. Вы можете испробовать эти варианты с помощью тестового проекта, чтобы узнать о возможностях вашей версии Visual Studio. You can explore these options with a test project to learn what’s available in your version of Visual Studio.

Каждый проект Python имеет один назначенный файл запуска, выделенный полужирным шрифтом в обозревателе решений. Each Python project has one assigned start-up file, shown in boldface in Solution Explorer. Это файл, который запускается, когда вы запускаете отладку (F5 или Отладка > Начать отладку) или выполняете проект в интерактивном окне (SHIFT+ALTF+5 или Отладка > Выполнить проект в интерактивном окне Python). The startup file is the file that’s run when you start debugging (F5 or Debug > Start Debugging) or when you run your project in the Interactive window (Shift+Alt+F5 or Debug > Execute Project in Python Interactive). Чтобы изменить его, щелкните правой кнопкой мыши новый файл и выберите действие Назначить автозапускаемым элементом (или Задать как файл запуска в ранних версиях Visual Studio). To change it, right-click the new file and select Set as Startup Item (or Set as Startup File in older versions of Visual Studio).

Если удалить выбранный файл запуска из проекта и не выбрать новый, Visual Studio не будет знать, с какого файла Python нужно начинать выполнение проекта. If you remove the selected startup file from a project and don’t select a new one, Visual Studio doesn’t know what Python file to start with when you try to run the project. В этом случае в Visual Studio 2017 версии 15.6 и более поздних версий возникает ошибка. В более ранних версиях либо открывается окно вывода с запущенным интерпретатором Python, либо окно вывода появляется, но почти сразу же исчезает. In this case, Visual Studio 2017 version 15.6 and later shows an error; earlier versions either open an output window with the Python interpreter running, or you see the output window appear but then disappear almost immediately. Если у вас возникла подобная ситуация, убедитесь, что назначен файл запуска. If you encounter any of these behaviors, check that you have an assigned startup file.

Чтобы окно вывода оставалось открытым, щелкните правой кнопкой мыши проект, выберите Свойства, откройте вкладку Отладка, а затем добавьте -i в поле Аргументы интерпретатора. If you want to keep the output window open for any reason, right-click your project, select Properties, select the Debug tab, then add -i to the Interpreter Arguments field. Этот аргумент вынуждает интерпретатор перейти в интерактивный режим после завершения программы, оставив окно открытым, пока вы не нажмете клавиши CTRL+Z > ВВОД для выхода. This argument causes the interpreter to go into interactive mode after a program completes, thereby keeping the window open until you enter Ctrl+Z > Enter to exit.

Новый проект всегда по умолчанию связан с глобальной средой Python. A new project is always associated with the default global Python environment. Чтобы связать проект с другим окружением (включая виртуальные), в проекте щелкните правой кнопкой мыши узел Окружения Python и выберите команду добавления или удаления окружений Python. To associate the project with a different environment (including virtual environments), right-click the Python Environments node in the project, select Add/Remove Python Environments, and select the ones you want.

Новый проект всегда по умолчанию связан с глобальной средой Python. A new project is always associated with the default global Python environment. Чтобы связать проект с другим окружением (в том числе виртуальным), в проекте щелкните правой кнопкой мыши узел Окружения Python и выберите команду Добавить окружение. , а затем выберите нужные окружения. To associate the project with a different environment (including virtual environments), right-click the Python Environments node in the project, select Add Environment.., and select the ones you want. Можно также использовать элемент управления с раскрывающимся списком окружений на панели инструментов, чтобы выбрать окружение или добавить в проект новое. You can also use the environments drop-down control on the toolbar to select and environment or add another one to the project.

Чтобы изменить активное окружение, в обозревателе решений щелкните правой кнопкой мыши нужное окружение и выберите действие Активировать окружение. To change the active environment, right-click the desired environment in Solution Explorer and select Activate Environment as shown below. Дополнительные сведения см. в разделе о выборе окружения для проекта. For more information, see Select an environment for a project.

Шаблоны проектов Project templates

Visual Studio предоставляет несколько способов настройки проекта Python — с нуля или из существующего кода. Visual Studio gives you a number of ways to set up a Python project, either from scratch or from existing code. Чтобы использовать шаблон, выберите команду меню Файл > Создать > Проект или щелкните правой кнопкой мыши решение в обозревателе решений и выберите Добавить > Новый проект. В любом случае отобразится диалоговое окно Новый проект. To use a template, select the File > New > Project menu command or right-click the solution in Solution Explorer and select Add > New Project, both of which bring up the New Project dialog below. Чтобы просмотреть шаблоны конкретно для Python, выполните поиск по запросу «Python» или последовательно выберите Установленные > Python: To see Python-specific templates, either search on «Python» or select the Installed > Python node:

В следующей таблице перечислены шаблоны, доступные в Visual Studio 2017 и более поздних версий (не все шаблоны доступны в предыдущих версиях): The following table summarizes the templates available in Visual Studio 2017 and later (not all templates are available in all previous versions):

Шаблон Template	Описание Description
На основе существующего кода Python From existing Python code	Создает проект Visual Studio из существующего кода Python в структуре папок. Creates a Visual Studio project from existing Python code in a folder structure.
Приложение Python Python Application	Структура базового проекта для нового приложения Python с одним пустым исходным файлом. A basic project structure for a new Python application with a single, empty source file. По умолчанию проект выполняется в консоли интерпретатора глобальной среды по умолчанию, которую можно изменить, назначив другую среду. By default, the project runs in the console interpreter of the default global environment, which you can change by assigning a different environment.
Облачная служба Azure Azure cloud service	Проект для облачной службы Azure, написанный на Python. A project for an Azure cloud service written in Python.
Веб-проекты Web projects	Проекты для веб-приложений на базе различных платформ, включая Bottle, Django и Flask. Projects for web apps based on various frameworks including Bottle, Django, and Flask.
Приложение с IronPython IronPython Application	Аналогичен шаблону приложения Python, но по умолчанию использует интерпретатор IronPython, поддерживающий взаимодействие .NET и смешанный режим отладки с использованием языков .NET. Similar to the Python Application template, but uses IronPython by default enabling .NET interop and mixed-mode debugging with .NET languages.
Приложение WPF с IronPython IronPython WPF Application	Структура проекта, использующая IronPython с XAML-файлами Windows Presentation Foundation для пользовательского интерфейса приложения. A project structure using IronPython with Windows Presentation Foundation XAML files for the application’s user interface. Visual Studio предоставляет конструктор пользовательского интерфейса XAML, возможность написания кода программной части на Python, а также возможность запуска приложения без отображения консоли. Visual Studio provides a XAML UI designer, code-behind can be written in Python, and the application runs without displaying a console.
Веб-страница с IronPython и Silverlight IronPython Silverlight Web Page	Это проект IronPython, который выполняется в браузере с подключаемым модулем Silverlight. An IronPython project that runs in a browser using Silverlight. Код приложения Python добавляется на веб-страницу в виде скрипта. The application’s Python code is included in the web page as script. Стандартный тег скрипта получает часть кода JavaScript, который инициализирует IronPython, выполняющийся в Silverlight, откуда код Python может взаимодействовать с моделью DOM. A boilerplate script tag pulls down some JavaScript code that initializes IronPython running inside of Silverlight, from which your Python code can interact with the DOM.
Приложение Windows Forms с IronPython IronPython Windows Forms Application	Структура проекта, использующая IronPython с пользовательским интерфейсом, созданным с помощью кода и Windows Forms. A project structure using IronPython with UI created using code with Windows Forms. Приложение запускается без вывода консоли. The application runs without displaying a console.
Фоновое приложение (Интернет вещей) Background Application (IoT)	Поддерживает развертывание проектов Python для работы в качестве фоновых служб на устройствах. Supports deploying Python projects to run as background services on devices. Дополнительные сведения см. на странице центра разработчиков Интернета вещей Windows. Visit the Windows IoT Dev Center for more information.
Модуль расширения Python Python Extension Module	Этот шаблон отображается в области Visual C++, если вы уже установили Собственные средства разработки Python с рабочей нагрузкой Python в Visual Studio 2017 или более поздней версии (см. раздел Установка). This template appears under Visual C++ if you’ve installed the Python native development tools with the Python workload in Visual Studio 2017 or later (see Installation). Он предоставляет базовую структуру для библиотеки DLL расширения C++, как описано в статье Создание расширения C++ для Python. It provides the core structure for a C++ extension DLL, similar to what’s described on Create a C++ extension for Python.

Так как Python является интерпретируемым языком, проекты Python в Visual Studio не создают отдельный исполняемый файл, как это делают проекты, написанные на других компилируемых языках программирования (например, C#). Because Python is an interpreted language, Python projects in Visual Studio don’t produce a stand-alone executable like other compiled language projects (C#, for example). Дополнительные сведения см. в разделе вопросов и ответов. For more information, see questions and answers.

Создание проекта на основе имеющихся файлов Create a project from existing files

Описанный здесь процесс не перемещает и не копирует исходные файлы. The process described here does not move or copy the original source files. Если вы хотите работать с копией, сначала создайте дубликат папки. If you want to work with a copy, duplicate the folder first.

Запустите Visual Studio и последовательно выберите Файл > Создать > Проект. Launch Visual Studio and select File > New > Project.

В диалоговом окне Создание проекта выполните поиск по запросу «Python», выберите шаблон На основе существующего кода Python, укажите имя и расположение проекта, а затем нажмите кнопку ОК. In the New Project dialog, search for «Python», select the From Existing Python code template, give the project a name and location, and select OK.

В появившемся мастере задайте путь к существующему коду, фильтр для типов файлов и любые пути поиска, необходимые для проекта, а затем нажмите кнопку Далее. In the wizard that appears, set the path to your existing code, set a filter for file types, and specify any search paths that your project requires, then select Next. Если вы не знаете пути поиска, оставьте это поле пустым. If you don’t know what search paths are, leave that field blank.

В следующем диалоговом окне выберите файл запуска для проекта и нажмите кнопку Далее. In the next dialog, select the startup file for your project and select Next. (При необходимости выберите среду; в противном случае оставьте значения по умолчанию.) Обратите внимание, что в диалоговом окне отображаются только файлы в корневой папке. Если нужный файл находится во вложенной папке, не указывайте файл запуска и укажите его позже в обозревателе решений (инструкции см. ниже). (If desired, select an environment; otherwise accept the defaults.) Note that the dialog shows only files in the root folder; if the file you want is in a subfolder, leave the startup file blank and set it later in Solution Explorer (described below).

Выберите место, где следует сохранить файл проекта (файл .pyproj на диске). Select the location in which to save the project file (which is a .pyproj file on disk). При необходимости можно также включить автоматическое обнаружение виртуальных сред и настроить проект для разных веб-платформ. If applicable, you can also include auto-detection of virtual environments and customize the project for different web frameworks. Если вы не уверены, оставьте для этих параметров значения по умолчанию. If you’re unsure of these options, leave them set to the defaults.

Нажмите кнопку Готово. Visual Studio создаст проект и откроет его в обозревателе решений. Select Finish and Visual Studio creates the project and opens it in Solution Explorer. Если вы хотите переместить PYPROJ-файл в другое место, выберите его в обозревателе решений и щелкните Файл > Сохранить как. If you want to move the .pyproj file elsewhere, select it in Solution Explorer and choose File > Save As. Это действие обновляет ссылки на файлы в проекте, но не перемещает файлы с кодом. This action updates file references in the project but does not move any code files.

Чтобы указать другой файл запуска, найдите его в обозревателе решений, щелкните его правой кнопкой мыши и выберите пункт Задать как файл запуска. To set a different startup file, locate the file in Solution Explorer, right-click, and select Set as Startup File.

Связанные файлы Linked files

Связанные файлы — это файлы, которые добавлены в проект, но при этом находятся за пределами папок проекта приложения. Linked files are files that are brought into a project but typically reside outside of the application’s project folders. Они отображаются в обозревателе решений как обычные файлы с перекрывающимся значком ярлыка: They appear in Solution Explorer as normal files with an overlaid shortcut icon:

Связанные файлы указаны в файле PYPROJ с помощью элемента . Linked files are specified in the .pyproj file using the element. Связанные файлы могут быть неявными, если они используют относительный путь за пределами структуры каталогов, или явными, если они используют пути в обозревателе решений: Linked files are implicit if they use a relative path outside of the directory structure, or explicit if they use paths within Solution Explorer:

Связанные файлы игнорируются при выполнении любого из следующих условий: Linked files are ignored under any of the following conditions:

• Связанный файл содержит метаданные связи, и путь, указанный в атрибуте Include, находится в пределах каталога проекта. The linked file contains Link metadata and the path specified in the Include attribute lives within the project directory
• Связанный файл дублирует файл, который существует в иерархии проекта. The linked file duplicates a file that exists within the project hierarchy
• Связанный файл содержит метаданные связи, и путь является относительным путем вне иерархии проекта. The linked file contains Link metadata and the Link path is a relative path outside of the project hierarchy
• Путь связи является корневым. The link path is rooted

Работа со связанными файлами Work with linked files

Чтобы добавить существующий элемент в качестве связи, щелкните правой кнопкой мыши папку проекта, в которую вы хотите добавить файл, а затем выберите Добавить > Существующий элемент. To add an existing item as a link, right-click the folder in the project where you wish to add the file, then select Add > Existing Item. В открывшемся диалоговом окне выберите файл и щелкните Добавить как связь в раскрывающемся списке кнопки Добавить. In the dialog that appears, select a file and choose Add as Link from the drop-down on the Add button. Если конфликтующие файлы отсутствуют, эта команда создает связь в выбранной папке. Provided that there are no conflicting files, this command creates a link in the selected folder. Связь не добавится, если файл с таким именем уже существует или связь с этим файлом уже существует в проекте. However, the link is not added if there is already a file with the same name or a link to that file already exists in the project.

При попытке создать связь с файлом, который уже существует в папке проекта, он добавляется как обычный файл, а не как связанный. If you attempt to link to a file that already exists in the project folders, it is added as a normal file and not as a link. Чтобы преобразовать файл в связь, выберите Файл > Сохранить как и сохраните файл в расположение вне иерархии проекта. Visual Studio автоматически преобразует его в связь. To convert a file into a link, select File > Save As to save the file to a location outside of the project hierarchy; Visual Studio automatically converts it into a link. Аналогичным образом можно преобразовать связь обратно с помощью команды Файл > Сохранить как и сохранить файл в иерархии проекта. Similarly, a link can be converted back by using File > Save As to save the file somewhere within the project hierarchy.

При перемещении связанного файла в обозревателе решений связь также перемещается, но фактический файл при этом не затрагивается. If you move a linked file in Solution Explorer, the link is moved but the actual file is unaffected. Аналогичным образом, удаление связи приведет к удалению только связи, не затрагивая сам файл. Similarly, deleting a link removes the link without affecting the file.

Связанные файлы нельзя переименовать. Linked files cannot be renamed.

Ссылки References

Проекты Visual Studio поддерживают добавление ссылок на проекты и расширения, которые отображаются в узле Ссылки в обозревателе решений. Visual Studio projects support adding references to projects and extensions, which appear under the References node in Solution Explorer:

Ссылки на расширения обычно указывают зависимости между проектами и используются для обеспечения IntelliSense во время разработки или связывания во время компиляции. Extension references typically indicate dependencies between projects and are used to provide IntelliSense at design time or linking at compile time. Проекты Python используют ссылки подобным образом, но из-за динамической природы Python они в основном используются во время разработки для предоставления усовершенствованной функции IntelliSense. Python projects use references in a similar fashion, but due to the dynamic nature of Python they are primarily used at design time to provide improved IntelliSense. Они также могут использоваться для развертывания в Microsoft Azure с целью установки дополнительных зависимостей. They can also be used for deployment to Microsoft Azure to install additional dependencies.

Модули расширений Extension modules

Ссылка на файл PYD позволяет использовать IntelliSense для созданного модуля. A reference to a .pyd file enables IntelliSense for the generated module. Visual Studio загружает файл PYD в интерпретатор Python и анализирует его типы и функции. Visual Studio loads the .pyd file into the Python interpreter and introspects its types and functions. Программа также пытается выполнить синтаксический анализ строк функций в документе, чтобы предоставить справку по сигнатурам. It also attempts to parse the doc strings for functions to provide signature help.

Если в любой момент модуль расширения обновляется на диске, Visual Studio повторно анализирует модуль в фоновом режиме. If at any time the extension module is updated on disk, Visual Studio reanalyzes the module in the background. Это не влияет на поведение во время выполнения, но некоторые варианты завершения остаются недоступными до завершения анализа. This action has no effect on run-time behavior but some completions aren’t available until analysis is complete.

Необходимо добавить путь поиска к папке, содержащей модуль. You may also need to add a search path to the folder containing the module.

Проекты .NET .NET projects

При работе с IronPython можно добавить ссылки на сборки .NET, чтобы активировать использование IntelliSense. When working with IronPython, you can add references to .NET assemblies to enable IntelliSense. Для проектов .NET в решении щелкните правой кнопкой мыши узел Ссылки в проекте Python, выберите Добавить ссылку, щелкните вкладку Проекты и найдите нужный проект. For .NET projects in your solution, right-click the References node in your Python project, select Add Reference, select the Projects tab, and browse to the desired project. Для библиотек DLL, которые вы скачали отдельно, выберите вкладку Обзор и перейдите к требуемой библиотеке DLL. For DLLs that you’ve downloaded separately, select the Browse tab instead and browse to the desired DLL.

Проекты WebPI WebPI projects

Можно добавить ссылки на записи продукта WebPI для развертывания в облачных службах Microsoft Azure, где можно установить дополнительные компоненты с помощью веб-канала WebPI. You can add references to WebPI product entries for deployment to Microsoft Azure Cloud Services where you can install additional components via the WebPI feed. По умолчанию отображаемый веб-канал предназначен только для Python и содержит Django, CPython и другие основные компоненты. By default, the feed displayed is Python-specific and includes Django, CPython, and other core components. Также можно выбрать собственный веб-канал, как показано ниже. You can also select your own feed as shown below. При публикации в Microsoft Azure задача установки устанавливает все продукты, на которые имеются ссылки. When publishing to Microsoft Azure, a setup task installs all of the referenced products.

Проекты WebPI недоступны в Visual Studio 2017 или Visual Studio 2019. WebPI projects is not available in Visual Studio 2017 or Visual Studio 2019.