Projetos do Python no Visual Studio

Geralmente, os aplicativos Python são definidos usando apenas pastas e arquivos. Essa estrutura pode se tornar complexa à medida que os aplicativos crescem e acabam envolvendo arquivos gerados automaticamente, como JavaScript para aplicativos Web e assim por diante. Um projeto do Visual Studio pode ajudar você a gerenciar a complexidade. O projeto (um arquivo .pyproj) identifica todos os arquivos de origem e de conteúdo associados a ele. Ele também contém informações de build de cada arquivo, mantém as informações para integração com sistemas de controle de código-fonte e ajuda a organizar o aplicativo em componentes lógicos.

Os projetos são sempre gerenciados em uma solução do Visual Studio. Uma solução pode conter vários projetos que podem fazer referência uns aos outros, como um projeto do Python que faz referência a um projeto do C++ que implementa um módulo de extensão. Com essa relação, o Visual Studio compila automaticamente o projeto em C++ (se for necessário) ao iniciar a depuração do projeto em Python. Para obter mais informações, consulte Soluções e projetos no Visual Studio.

O Visual Studio fornece vários modelos de projeto do Python para criar rapidamente vários tipos de estruturas de aplicativos. Você pode escolher um modelo para criar um projeto em uma árvore de pastas existente ou criar um projeto limpo e vazio. Para obter uma lista de modelos disponíveis, consulte a tabela na seção Modelos de projeto.

Dicas para trabalhar com projetos do Python

Você não precisa usar projetos para executar código do Python no Visual Studio, mas há benefícios em fazer isso. Para começar, examine as considerações a seguir sobre como trabalhar com projetos e o Python.

• No Visual Studio 2019 e posterior, você pode abrir uma pasta com código do Python e executar o código sem criar arquivos de projeto e solução do Visual Studio.

  As etapas guiadas para essa abordagem estão disponíveis no artigo Início Rápido: Abrir e executar código do Python em uma pasta.

• Você não precisa de um projeto para executar código do Python no Visual Studio. Todas as versões do Visual Studio funcionam bem com códigos do Python.

  Você pode abrir um arquivo do Python por conta própria e acessar imediatamente os recursos de preenchimento automático, IntelliSense e depuração. No entanto, há algumas possíveis desvantagens em trabalhar com o código sem um projeto:

  • Como o código sempre usa o ambiente global padrão, talvez você veja preenchimentos incorretos ou erros, caso o código se destine a outro ambiente.
  • O Visual Studio analisa todos os arquivos e pacotes na pasta da qual o arquivo é aberto. Esse processo pode consumir um tempo considerável de CPU.

• Você pode criar um projeto do Visual Studio com base no código existente. Essa abordagem é descrita na seção Criar um projeto com arquivos existentes.

Tarefas básicas do projeto: arquivos, ambientes e inicialização

Ao usar projetos com seu código do Python, você realiza tarefas básicas, incluindo adicionar arquivos, atribuir um arquivo de inicialização e definir o ambiente do interpretador do Python.

À medida que desenvolve seu aplicativo, normalmente você precisa adicionar novos arquivos de diferentes tipos ao projeto. É fácil adicionar arquivos. Clique com o botão direito do mouse no projeto, selecione Adicionar>Item existente e navegue até encontrar o tipo de arquivo a ser adicionado. A opção Adicionar>Novo Item abre uma caixa de diálogo que mostra modelos de item que você pode usar para criar o arquivo. As opções incluem arquivos do Python vazios, uma classe do Python, um teste de unidade e vários arquivos relacionados a aplicativos Web. Explore as opções de modelos com um projeto de teste para saber o que está disponível em sua versão do Visual Studio. Para obter mais informações, veja a referência de modelos de item.

Cada projeto do Python tem um arquivo de inicialização atribuído, que é mostrado em negrito no Gerenciador de Soluções. O arquivo de inicialização é executado quando você começa a depuração (selecionando F5 ou Depurar>Iniciar Depuração) ou quando você executa o projeto na Janela interativa. Você pode abrir essa janela com o atalho de teclado Shift + Alt + F5 ou selecionando Depurar>Executar Projeto no Python Interativo. Para alterar o arquivo de inicialização, clique com o botão direito do mouse no arquivo que deseja usar e selecione Definir como Item de Inicialização (ou Definir como Arquivo de Inicialização em versões mais antigas do Visual Studio).

Se você remover o arquivo de inicialização selecionado de um projeto e não selecionar um arquivo alternativo, o Visual Studio não saberá com qual arquivo do Python usar para iniciar o projeto. Nesse caso, o Visual Studio 2017 versão 15.6 e posteriores mostrará um erro. Versões anteriores abrem uma janela de saída com o interpretador do Python em execução ou a janela de saída é aberta e, em seguida, fechada imediatamente. Se você observar algum desses comportamentos, verifique se haverá um arquivo de inicialização atribuído.

Dica

Para manter a janela de saída aberta, clique com o botão direito do mouse em seu projeto e selecione Propriedades. Na caixa de diálogo, selecione a guia Depurar e adicione o sinalizador -i ao campo Argumentos do Interpretador. Esse argumento faz com que o interpretador entre no modo interativo após a conclusão de um programa. A janela permanece aberta até você fechá-la, como usando o atalho de tecladoCtrl+E+Enter.

Um novo projeto sempre é associado ao ambiente global padrão do Python. Para associar o projeto a outro ambiente (incluindo ambientes virtuais), clique com o botão direito do mouse no nó Ambientes do Python no projeto. Selecione Adicionar Ambiente e selecione os ambientes desejados. Você também pode usar o controle de lista suspensa de ambientes na barra de ferramentas para selecionar outro ambiente para o projeto.

Para alterar o ambiente ativo, clique com o botão direito do mouse no ambiente desejado no Gerenciador de Soluções e selecione Ativar Ambiente, conforme mostrado na imagem a seguir. Para obter mais informações, confira Selecionar um ambiente para um projeto.

Modelos de projeto

O Visual Studio fornece muitas maneiras para configurar um projeto do Python, do zero ou com um código existente. Para usar um modelo, selecione Arquivo>Novo>Projeto ou clique com o botão direito do mouse na solução no Gerenciador de Soluções e selecione Adicionar>Novo Projeto. Na caixa de diálogo novo projeto, você pode ver modelos específicos do Python pesquisando em Python ou selecionando o nó Linguagem>Python:

Os modelos a seguir estão disponíveis no Visual Studio versão 2022.

Modelo	Descrição
Com base em um código existente do Python	Cria um projeto do Visual Studio com base em um código existente do Python em uma estrutura de pastas.
Aplicativo do Python	Fornece uma estrutura de projeto básica para um novo aplicativo do Python com um único arquivo de origem vazio. Por padrão, o projeto é executado no interpretador do console do ambiente global padrão. Você pode alterar atribuindo um ambiente diferente.
Projetos Web	Projetos para aplicativos Web baseados em várias estruturas, incluindo Bottle, Django e Flask.
Aplicativo em segundo plano (IoT)	Dá suporte à implantação de projetos do Python a serem executados como serviços em segundo plano em dispositivos. Para obter mais informações, confira a Central de desenvolvedores de IoT do Windows.
Módulo de Extensão do Python	Esse modelo será exibido no Visual C++ se você instalar as ferramentas de desenvolvimento nativo do Python com a carga de trabalho do Python no Visual Studio 2017 ou posteriores (consulte Instalação). O modelo fornece a estrutura principal para uma DLL de extensão do C++, semelhante à estrutura descrita em Criar uma extensão do C++ para Python.

Observação

Como o Python é uma linguagem interpretada, os projetos em Python no Visual Studio não produzem um executável autônomo como outros projetos de linguagem compilada, como C#. Para saber mais, confira Perguntas e respostas.

Criar um projeto com base em um código existente

Siga estas etapas para criar um projeto com arquivos existentes.

Importante

O processo a seguir não move nem copia nenhum arquivo de origem original. Se você quiser trabalhar com uma cópia de seus arquivos, primeiro duplique a pasta e, em seguida, crie o projeto.

1. Inicie o Visual Studio e selecione Arquivo>Novo>Projeto.

2. Na caixa de diálogo Criar um projeto, pesquise python, selecione o modelo De código do Python existente e Avançar.

3. Na caixa de diálogo Configurar novo projeto, insira um Nome e Local para o projeto, escolha a solução para contê-lo e selecione Criar.

4. No assistente Criar novo projeto do código Python existente, defina o Caminho da pasta para o código existente, defina um Filtro para tipos de arquivo e especifique os Caminhos de pesquisa necessários para o projeto e selecione Avançar. Se você não souber os caminhos de pesquisa, deixe o campo em branco.

   

5. Na próxima página, selecione o Arquivo de inicialização do projeto. O Visual Studio seleciona o interpretador e a versão globais padrão do Python. Você pode alterar o ambiente usando o menu suspenso. Quando estiver pronto, selecione Próximo.

   Observação

   A caixa de diálogo mostra apenas arquivos na pasta raiz. Se o arquivo desejado estiver em uma subpasta, deixe o arquivo de inicialização em branco. Você pode definir o arquivo de inicialização no Gerenciador de Soluções, conforme descrito em uma etapa posterior.

   

6. Selecione o local para armazenar o arquivo de projeto (um arquivo .pyproj no disco). Caso se aplique, também será possível incluir a detecção automática de ambientes virtuais e personalizar o projeto para outras estruturas da Web. Se você não tiver certeza sobre essas opções, deixe os campos com as configurações padrão.

   

7. Selecione Concluir.

   O Visual Studio cria e abre o projeto no Gerenciador de Soluções. Se você quiser mover o arquivo .pyproj para um local diferente, selecione o arquivo no Gerenciador de Soluções e selecione Arquivo>Salvar comona barra de ferramentas. Essa ação atualizará as referências de arquivo no projeto, mas não moverá nenhum arquivo de código.

8. Para definir um arquivo de inicialização diferente, localize o arquivo no Gerenciador de Soluções, clique com o botão direito do mouse e selecione Definir como Arquivo de Inicialização.

Arquivos vinculados

Os arquivos vinculados são aqueles que são inseridos em um projeto, mas que geralmente residem fora das pastas do projeto do aplicativo. Esses arquivos aparecem no Gerenciador de Soluções como arquivos normais com um ícone de atalho sobreposto:

Os arquivos vinculados são especificados no arquivo .pyproj usando o elemento <Compile Include="...">. Os arquivos vinculados serão implícitos se usarem um caminho relativo fora da estrutura de diretório. Se os arquivos usarem caminhos no Gerenciador de Soluções, os arquivos vinculados serão explícitos. O exemplo a seguir mostra arquivos explicitamente vinculados:

<Compile Include="..\test2.py">
    <Link>MyProject\test2.py</Link>
</Compile>

Arquivos vinculados são ignorados nas seguintes condições:

• O arquivo vinculado contém metadados do Linke o caminho especificado no atributo Include reside no diretório do projeto.
• O arquivo vinculado duplica um arquivo que existe na hierarquia do projeto.
• O arquivo vinculado contém metadados do Link e o caminho do Link é um caminho relativo fora da hierarquia do projeto.
• O caminho do link tem raiz.

Trabalhar com arquivos vinculados

Para adicionar um item existente como um link, clique com o botão direito do mouse na pasta do projeto em que deseja adicionar o arquivo e, em seguida, selecione Adicionar>Item Existente. Na caixa de diálogo, selecione um arquivo e, em seguida, selecione Adicionar>Adicionar como Link. Se não existirem arquivos conflitantes, esse comando criará um link na pasta selecionada. No entanto, o link não será adicionado se existir um arquivo com o mesmo nome ou se já existir um link para esse arquivo no projeto.

Se você tentar vincular a um arquivo que já existe nas pastas do projeto, ele será adicionado como um arquivo normal e não como um link. Para converter um arquivo em um link, selecione Arquivo>Salvar como para salvar o arquivo em um local fora da hierarquia do projeto. O Visual Studio converte automaticamente o arquivo em um link. Da mesma forma, um link pode ser convertido novamente usando a opção Arquivo>Salvar Como para salvar o arquivo em algum lugar na hierarquia do projeto.

Se você mover um arquivo vinculado no Gerenciador de Soluções, o link será movido, mas o arquivo real não será afetado. Da mesma forma, a exclusão de um link removerá o link sem afetar o arquivo.

Arquivos vinculados não podem ser renomeados.

Referências

Os projetos do Visual Studio dão suporte à adição de referências a projetos e extensões, que são exibidas no nó Referências do Gerenciador de Soluções:

Geralmente, referências de extensão indicam dependências entre projetos e são usadas para fornecer o IntelliSense em tempo de design ou a vinculação em tempo de compilação. Os projetos do Python usam referências de maneira semelhante, mas devido à natureza dinâmica do Python, elas são usadas principalmente em tempo de design para fornecer um IntelliSense avançado. Elas também podem ser usadas para implantação no Microsoft Azure para instalar outras dependências.

Trabalhar com módulos de extensão

Uma referência a um arquivo .pyd habilita o IntelliSense no módulo gerado. O Visual Studio carrega o arquivo .pyd no interpretador do Python e examina seus tipos e suas funções. O Visual Studio também tenta analisar as cadeias de caracteres doc em funções para fornecer ajuda da assinatura.

Se, a qualquer momento, o módulo de extensão é atualizado em disco, o Visual Studio analisa o módulo novamente em segundo plano. Essa ação não tem nenhum efeito no comportamento do runtime, mas alguns preenchimentos não estarão disponíveis até que a análise seja concluída.

Você também pode ter que adicionar um caminho de pesquisa à pasta que contém o módulo.

Trabalhar com projetos do .NET

Ao trabalhar com o IronPython, é possível adicionar referências aos assemblies do .NET para habilitar o IntelliSense. Em projetos do .NET, clique com o botão direito do mouse no nó Referências em seu projeto do Python e selecione Adicionar Referência. Na caixa de diálogo, selecione a guia Projetos e navegue até o projeto desejado. Para as DLLs baixadas separadamente, selecione a guia Procurar e procure a DLL desejada.

Como as referências no IronPython não estão disponíveis até depois de uma chamada ao método clr.AddReference('<AssemblyName>'), você também precisa adicionar uma chamada de método clr.AddReference apropriada ao assembly. Essa chamada normalmente é adicionada no início do código. Por exemplo, o código criado pelo modelo de projeto Aplicativo Windows Forms do IronPython (disponível no Visual Studio 2019) do Visual Studio inclui duas chamadas no início do arquivo:

import clr
clr.AddReference('System.Drawing')
clr.AddReference('System.Windows.Forms')

from System.Drawing import *
from System.Windows.Forms import *

# Other code omitted

Trabalhar com projetos do WebPI

É possível adicionar referências a entradas de produtos do WebPI (Web Platform Installer) para implantação nos Serviços de Nuvem do Microsoft Azure, em que é possível instalar componentes adicionais por meio do feed do WebPI. Por padrão, o feed exibido é específico ao Python e inclui o Django, o CPython e outros componentes básicos. Você também pode selecionar seu feed, conforme mostrado na imagem a seguir. Ao publicar no Microsoft Azure, uma tarefa de instalação instala todos os produtos referenciados.

Importante

Os projetos do WebPI não estão disponíveis no Visual Studio 2017 nem no Visual Studio 2019.

Conteúdo relacionado

• Soluções e projetos no Visual Studio
• Selecionar um ambiente para um projeto
• Instalar o suporte de Python no Visual Studio