Editar o código Python e usar o Intellisense

Como você passa muito tempo dedicado ao desenvolvimento no editor de códigos, o Suporte para Python no Visual Studio fornece funcionalidade para ajudá-lo a ser mais produtivo. Os recursos incluem o realce de sintaxe do IntelliSense, o preenchimento automático, a ajuda de assinatura, as substituições de método, a pesquisa e a navegação.

O editor de códigos é integrado à janela Interativa no Visual Studio. À medida que você trabalha, a troca de código entre as duas janelas é simples. Para obter mais informações, consulte Etapa 3 do tutorial: Usar a janela do REPL Interativo e Usar a janela Interativa – comando Enviar para Interativa.

A Estrutura de tópicos ajuda você a manter o foco em seções específicas do código. Para obter uma documentação geral sobre edição do código no Visual Studio, confira Recursos do editor de código.

O Pesquisador de Objetos do Visual Studio possibilita que você inspecione as classes do Python definidas em cada módulo e as funções definidas nessas classes. Acesse esse recurso pelo menu Exibir ou utilizando o atalho do teclado Ctrl+Alt+J.

Usar os recursos do IntelliSense

O IntelliSense fornece preenchimentos, ajuda da assinatura, informações rápidas e coloração de código. O Visual Studio 2017 versão 15.7 e posteriores também dão suporte a dicas de tipo.

Para melhorar o desempenho, o IntelliSense no Visual Studio 2017 versão 15.5 e em versões anteriores depende do banco de dados de preenchimento que é gerado para cada ambiente do Python no projeto. Poderá ser necessário atualizar o banco de dados ao adicionar, remover ou atualizar pacotes. O status do banco de dados é mostrado na janela Ambientes do Python (um complemento do Gerenciador de Soluções) na guia IntelliSense. Para obter mais informações, consulte a Referência da janela Ambientes.

O Visual Studio 2017 versão 15.6 e posterior usa um modo diferente para fornecer as conclusões de IntelliSense que não são dependentes do banco de dados.

Preenchimentos

Preenchimentos aparecem como instruções, identificadores e outras palavras que podem ser inseridas adequadamente no local atual no editor. O IntelliSense preenche a lista de opções com base no contexto e filtra itens incorretos ou confusos. Em geral, os preenchimentos são acionados pela inserção de diferentes instruções (como import) e operadores (incluindo um ponto final), mas eles podem aparecer a qualquer momento por meio da seleção do atalho do teclado Ctrl+J +Espaço.

Quando uma lista de preenchimento é aberta, é possível pesquisar o preenchimento que você deseja usando as teclas de direção e o mouse ou continuando a digitação. Conforme você digita mais letras, a lista é filtrada ainda mais para mostrar os prováveis preenchimentos. Você também pode usar atalhos, como:

• Digitar letras que não estão no início do nome, como “parse” para encontrar “argparse”.
• Digitar apenas letras que estão no início de palavras, como “abc” para encontrar “AbstractBaseClass” ou “air” para encontrar “as_integer_ratio”.
• Ignorar letras, como “b64” para encontrar “base64”.

Estes são alguns exemplos:

Os preenchimentos de membro aparecem automaticamente quando você digita um ponto final depois de uma variável ou um valor, juntamente com os métodos e os atributos dos tipos possíveis. Se for possível que uma variável seja de mais de um tipo, a lista incluirá todas as possibilidades de todos os tipos. Informações adicionais são mostradas para indicar quais tipos oferecem suporte a cada conclusão. Quando todos os tipos possíveis oferecem suporte a uma conclusão, nenhuma anotação é exibida.

Por padrão, os membros “dunder” (membros que começam e terminam com um sublinhado duplo) não são exibidos. Em geral, esses membros não devem ser acessados diretamente. Se você precisar usar um dunder, digite o sublinhado duplo à esquerda para adicionar esses preenchimentos à lista:

As instruções import e from ... import exibem uma lista de módulos que podem ser importados. A instrução from ... import produz uma lista que inclui os membros que podem ser importados do módulo especificado.

As instruções raise e except exibem listas de classes que provavelmente são tipos de erros. A lista pode não incluir todas as exceções definidas pelo usuário, mas ela ajuda você a encontrar as exceções internas adequadas rapidamente:

A seleção do símbolo @ (arroba) inicializa um decorador e exibe outros decoradores potenciais. Muitos desses itens não podem ser utilizados como decoradores. Consulte a documentação da biblioteca para estabelecer qual decorador utilizar.

Para obter mais informações, consulte Opções: resultados de conclusão.

Dicas de tipo

As dicas de tipo estão disponíveis no Visual Studio 2017 versão 15.7 e em versões posteriores.

As "dicas de tipo" no Python 3.5+ (PEP 484) (python.org) são uma sintaxe de anotação para funções e classes que indicam os tipos de argumentos, valores de retorno e atributos de classe. O IntelliSense exibe dicas de tipo quando você focaliza argumentos, variáveis e chamadas de função que contêm essas anotações.

No exemplo a seguir, a classe Vector é declarada como o tipo List[float] e a função scale contém dicas de tipo para seus argumentos e o valor retornado. Passar o mouse sobre uma chamada da função mostra as dicas de tipo:

No próximo exemplo, você pode ver como os atributos anotados da classe Employee aparecem no pop-up de conclusão de IntelliSense para um atributo:

Também é útil validar as dicas de tipo em todo o seu projeto, pois erros normalmente não aparecem até o tempo de execução. Para isso, o Visual Studio integra a ferramenta padrão do setor MyPy usando o comando de menu de contexto Python>Executar Mypy no Gerenciador de Soluções:

A execução do comando solicitará que você instale o pacote do MyPy, se necessário. Depois, o Visual Studio executará o MyPy para validar as dicas de tipo em todos os arquivos Python do projeto. Os erros aparecem na janela Lista de Erros do Visual Studio. Selecionar um item na janela navega para a linha apropriada no seu código.

Como um exemplo simples, a definição de função a seguir contém uma dica de tipo que indica que o argumento input é do tipo str, enquanto a chamada para essa função tenta passar um número inteiro:

def commas_to_colons(input: str):
    items = input.split(',')
    items = [x.strip() for x in items]
    return ':'.join(items)

commas_to_colons(1)

Usar o comando Execute Mypy neste código gera o seguinte erro:

Observação

Para as versões do Python anteriores à 3.5, o Visual Studio também exibe dicas de tipo fornecidas por meio de arquivos stub do Typeshed (.pyi). Você pode usar arquivos stub quando não quiser incluir dicas de tipo diretamente no código ou para criar dicas de tipo para uma biblioteca que não as usa diretamente. Para obter mais informações, confira Criar stubs para módulos do Python no wiki de projeto do MyPy.

O Visual Studio ainda não oferece suporte a dicas de tipo nos comentários.

Ajuda da assinatura

Quando você escreve código que chama uma função, a ajuda de assinatura é exibido ao digitar o primeiro parêntese (. Ela apresenta toda a documentação disponível e informações sobre os parâmetros. Acesse a ajuda de assinatura pelo atalho do teclado Ctrl+Shift+Space dentro de uma chamada de função. As informações exibidas dependem das cadeias de caracteres de documentação no código-fonte da função, mas incluem os valores padrão.

Dica

Para desabilitar a ajuda de assinatura, acesse Ferramentas>Opções>Editor de Texto>Python>Geral. Desmarque a caixa de seleção Conclusão da instrução>Informações sobre parâmetros.

Informações rápidas

Focalizar o ponteiro do mouse em um identificador exibe uma dica de ferramenta Informações Rápidas. Dependendo do identificador, as Informações Rápidas poderão exibir os possíveis valores ou tipos, toda a documentação disponível, os tipos de retorno e os locais de definição:

Coloração de código

A coloração de código usa informações da análise de código para colorir variáveis, instruções e outras partes do código. As variáveis relacionadas aos módulos ou às classes poderão ser exibidas em uma cor diferente das funções ou dos demais valores. Os nomes de parâmetro poderão ser exibidos em uma cor diferente das variáveis locais ou globais. Por padrão, as funções não são exibidas em negrito.

Para personalizar as cores, acesse Ferramentas>Opções>Ambiente>Fontes e Cores. Na lista Itens de exibição, altere as entradas desejadas para Python:

Inserir snippets de código

Os snippets de código são fragmentos de código que podem ser inseridos nos arquivos usando um atalho do teclado e pressionando Tab. Você também pode usar os comandos Editar>IntelliSense>Inserir Snippet e Cercar com, selecionar Python e escolher o snippet desejado.

Por exemplo, class é um atalho para um snippet de código que insere uma definição de classe. Você vê o snippet aparecer na lista de conclusão automática ao digitar class:

Pressionar Tab gera o restante da classe. Depois, digite o nome e a lista de bases, percorra os campos realçados com Tab e pressione Enter para começar a digitar o corpo.

Comandos de menu

Ao usar o comando de menu Editar>IntelliSense>Inserir Snippet de Código, primeiro selecione Python, depois escolha o snippet desejado:

O comando Editar>IntelliSense>Cercar com coloca a seleção atual no editor de texto dentro de um elemento estrutural escolhido. Suponha que você tem um trecho de código semelhante ao seguinte exemplo:

sum = 0
for x in range(1, 100):
    sum = sum + x

Selecionar esse código e escolher o comando Envolver com exibe uma lista de snippets de código disponíveis. A escolha de def na lista de snippets coloca o código selecionado em uma definição de função. Use a tecla Tab para navegar entre o nome e os argumentos realçados da função:

Examinar snippets disponíveis

Os snippets de código disponíveis podem ser visualizados no Gerenciador de Snippets de Código. Para acessar esse recurso, abra Ferramentas>Gerenciador de Snippets de Código e escolha Python como linguagem:

Para criar seus próprios snippets de código, confira Passo a passo: Criar um snippet de código.

Se você escrever um ótimo snippet de código que gostaria de compartilhar, fique à vontade para postá-lo em linhas gerais e contar para nós. Talvez possamos incluí-lo em uma versão futura do Visual Studio.

Navegar pelo seu código

O suporte ao Python no Visual Studio proporciona diversas formas de navegar rapidamente pelo código, incluindo bibliotecas com o código-fonte disponível. Há bibliotecas disponíveis com código-fonte para a barra de navegação e para os comandos Ir para Definição, Ir para e Localizar Todas as Referências. Use também o Pesquisador de Objetos do Visual Studio.

Barra de navegação

A barra de navegação é exibida na parte superior de cada janela do editor e inclui uma lista de dois níveis de definições. A lista suspensa do lado esquerdo apresenta definições de classes e funções de nível superior no arquivo atual. A lista suspensa do lado direito contém as definições dentro do escopo mostrado do lado esquerdo. Conforme você usa o editor, as listas são atualizadas para mostrar o contexto atual e você também pode selecionar uma entrada dessas listas para ir diretamente para ela.

Dica

Para ocultar a barra de navegação, acesse Ferramentas>Opções>Editor de Texto>Python>Gerais e desmarque Configurações>Barra de navegação.

Ir para definição

O comando Ir para Definição vai rapidamente do uso de um identificador (como um nome de função, classe ou variável) para o local da definição do código-fonte. Para invocar o comando, clique com o botão direito do mouse em um identificador e escolha Ir para Definição ou posicione o cursor no identificador e pressione F12. O comando funciona em todo o código e nas bibliotecas externas em que o código-fonte esteja disponível. Se o código-fonte da biblioteca não estiver disponível, o comando Ir para Definição irá para a instrução import relevante de uma referência de módulo ou exibirá um erro.

Ir para

O comando Editar>Ir para (Ctrl+,) exibe uma caixa de pesquisa no editor em que é possível digitar qualquer cadeia de caracteres e ver as possíveis correspondências no código que definem uma função, uma classe ou uma variável que contém a cadeia de caracteres. Esse recurso fornece uma funcionalidade semelhante a Ir Para Definição, mas sem a necessidade de localizar um uso de um identificador.

Para navegar até a definição desse identificador, clique duas vezes em qualquer nome ou selecione o nome com as teclas de seta e pressione Enter.

Localizar Todas as Referências

O recurso Localizar Todas as Referências é uma maneira útil de descobrir o local em que um identificador específico é definido e usado, incluindo importações e atribuições. Para invocar o comando, clique com o botão direito do mouse em um identificador e escolha Localizar Todas as Referências ou posicione o cursor no identificador e pressione Shift+F12. Clicar duas vezes em um item da lista navegará para sua localização.

Conteúdo relacionado

• Formatar o código do Python
• Refatorar um código do Python
• Usar um linter