Depurar seu código Python no Visual Studio
O Visual Studio fornece uma experiência de depuração abrangente para Python. Neste artigo, você explora como anexar o depurador a processos em execução e avaliar expressões nas janelas Watch e Immediate. No depurador, você pode inspecionar variáveis locais, usar pontos de interrupção, avançar/retroceder/passar sobre instruções, Definir Próxima Instrução, e muito mais.
Para obter informações de depuração específicas do cenário, consulte os seguintes artigos:
Pré-requisitos
Visual Studio instalado com suporte para cargas de trabalho Python. Para obter mais informações, consulte Instalar suporte a Python no Visual Studio.
Código Python para usar com o depurador.
Depurar código com ou sem um projeto
Se você quiser controlar seu ambiente Python e argumentos, primeiro crie um projeto para seu código. Você pode criar um projeto com o modelo de projeto código Python From existente. Para obter mais informações, consulte Criar um projeto a partir de arquivos de código Python existentes.
No entanto, você não precisa de um projeto ou arquivo de solução no Visual Studio para depurar seu código Python. Para depurar o código em um arquivo Python autónomo, abra o arquivo no Visual Studio e selecione Depurar>Iniciar Depuração. O Visual Studio inicia o script com o ambiente padrão global e sem argumentos. Em seguida, você tem suporte total de depuração para seu código. Para obter mais informações, consulte ambientes do Python.
Explore a possibilidade de depuração básica
O fluxo de trabalho de depuração básico envolve pontos de interrupção de configurações, revisão de código, inspeção de valores e tratamento de exceções. Você pode iniciar uma sessão de depuração selecionando Depurar>Iniciar Depuração ou usar o F5 atalho de teclado. Para um projeto, essas ações iniciam o arquivo de inicialização com o ambiente ativo do projeto e quaisquer argumentos de linha de comando ou caminhos de pesquisa especificados para Propriedades do Projeto. Para configurar as propriedades, consulte Definir opções de depuração de projeto.
Definir o arquivo de inicialização do projeto
O arquivo de inicialização de um projeto é mostrado em negrito no Gerenciador de Soluções . Você pode escolher qual arquivo usar como arquivo de inicialização.
- Para especificar um arquivo de projeto como o arquivo de inicialização, clique com o botão direito do mouse no arquivo e selecione Definir como Item de Inicialização.
No Visual Studio 2017 versão 15.6 e posterior, você verá um alerta se não tiver um conjunto de arquivos de inicialização especificado. Versões anteriores do Visual Studio podem abrir uma janela Output com o interpretador Python em execução ou a janela Output abre e fecha brevemente.
Especificar o ambiente ativo
Se você estiver usando um arquivo de projeto, o depurador sempre começa com o ambiente Python ativo para o projeto. Você pode alterar o ambiente ativo atual. Para obter mais informações, consulte Selecionar um ambiente Python para um projeto.
Se você estiver depurando um arquivo de código Python autônomo, o Visual Studio iniciará o script com o ambiente padrão global e sem argumentos.
Definir pontos de interrupção
Os pontos de interrupção interrompem a execução do código em um ponto marcado para que você possa inspecionar o estado do programa.
Alguns pontos de interrupção em Python podem ser surpreendentes para desenvolvedores que trabalharam com outras linguagens de programação. Em Python, todo o arquivo é código executável, então Python executa o arquivo quando ele é carregado para processar qualquer classe de nível superior ou definições de função. Se um ponto de interrupção for definido, poderá encontrar o depurador interrompendo parte de uma declaração de classe. Esse comportamento é correto, embora às vezes seja surpreendente.
Para definir um ponto de interrupção, selecione na margem esquerda do editor de código ou clique com o botão direito do mouse em uma linha de código e selecione Ponto de interrupção>Inserir ponto de interrupção. Um ponto vermelho aparece em cada linha que tem um ponto de interrupção definido.
Para remover um ponto de interrupção, selecione o ponto vermelho ou clique com o botão direito do mouse na linha de código e selecione Ponto de interrupção>Excluir ponto de interrupção. Você também pode desativar um ponto de interrupção selecionando o ponto vermelho e selecionando Ponto de interrupção>Desativar ponto de interrupção.
Definir condições e ações
Você pode personalizar as condições sob as quais um ponto de interrupção é acionado, como quebrar somente quando uma variável é definida como um determinado valor ou intervalo de valores.
Para definir condições, clique com o botão direito do rato no ponto vermelho do ponto de interrupção, selecione Condições. A caixa de diálogo Configurações do ponto de interrupção é aberta.
Na caixa de diálogo, você pode adicionar várias condições e criar expressões condicionais usando código Python. Para obter detalhes completos sobre esse recurso no Visual Studio, consulte Condições de ponto de interrupção.
Você também tem as opções para definir Ações para um ponto de interrupção. Você pode criar uma mensagem para fazer logon na janela Output e, opcionalmente, especificar para continuar a execução automaticamente.
Registrar uma mensagem cria um ponto de rastreamento que não adiciona código de log diretamente à sua aplicação.
Dependendo de como você configura condições e ações para um ponto de interrupção, o ícone vermelho na margem esquerda muda para indicar suas configurações. Você pode ver a forma do ponto, um temporizador de relógio ou um diamante.
Passo a passo pelo código
Quando o Visual Studio interrompe a execução do código num ponto de paragem, há vários comandos que pode usar para navegar pelo seu código ou executar blocos de código antes de parar novamente. Os comandos estão disponíveis em alguns locais no Visual Studio, incluindo a barra de ferramentas Depurador, o menu de depuração, o menu de contexto do botão direito do mouse no editor de código e por meio de atalhos de teclado.
A tabela a seguir resume esses comandos e fornece o atalho de teclado:
| Comando | Atalho | Descrição |
|---|---|---|
| Pare | Shift + F5 | Pare a sessão de depuração. |
| Reiniciar | Ctrl + Shift + F5 | Reinicie a sessão de depuração atual. |
| Continuar | F5 | Execute o código até atingir o próximo ponto de interrupção. |
| Entre em | F11 | Execute a próxima instrução e pare. Se a próxima instrução for uma chamada para uma função, o depurador para na primeira linha da função chamada. |
| Passo Sobre | F10 | Execute a próxima instrução, incluindo fazer uma chamada para uma função (executando todo o seu código) e aplicar qualquer valor de retorno. Este comando permite-lhe ignorar facilmente funções que não precisa de depurar. |
| Saia | Shift+F11 | Execute o código até o final da função atual e, em seguida, vá para a instrução de chamada. Este comando é útil quando você não precisa depurar o restante da função atual. |
| Executar até o cursor | Ctrl+F10 | Execute o código até à posição do cursor no editor. Este comando permite que você ignore facilmente um segmento de código que você não precisa depurar. |
| Definir a próxima instrução | Ctrl+Shift+F10 | Altere o ponto de execução atual no código para o local do cursor. Este comando permite que você omita um segmento de código de ser executado, como quando você sabe que o código está com defeito ou produz um efeito colateral indesejado. |
| Mostrar próxima declaração | Alt+Num+\ | Retorne ao próximo comando a executar na execução do código. Este comando ajuda a encontrar o local no seu código onde o depurador está parado. |
Inspecionar e modificar valores
Ao parar a execução de código no depurador, você pode inspecionar e modificar os valores das variáveis. Você também pode usar a janela Watch para monitorar variáveis individuais e expressões personalizadas. Para obter mais informações, consulte Inspecionar variáveis.
Para exibir um valor usando o recurso DataTips durante a depuração, passe o mouse sobre qualquer variável no editor. Você pode selecionar o valor da variável para alterá-lo:
Para usar a janela Autos, selecione Depurar >Windows>Autos. Esta janela contém variáveis e expressões próximas à instrução atual. Você pode clicar duas vezes na coluna de valor ou selecionar e digitar F2 para editar o valor:
Para obter mais informações sobre como usar a janela Autos, consulte Inspecionar variáveis nas janelas Autos e Locais.
Para usar a janela Locais, selecione Depurar>Windows>Locais. Esta janela exibe todas as variáveis que estão no escopo atual, que podem ser editadas novamente:
Para mais informações sobre como usar a janela Locais, consulte Inspecionar variáveis nas janelas de Automáticos e Locais.
Para usar as janelas do Watch, selecione Depurar >Windows>Watch>Watch 1-4. Esta opção permite inserir expressões Python arbitrárias e visualizar os resultados. As expressões são reavaliadas para cada etapa:
Para obter mais informações sobre como usar a janela Observação, consulte Definir uma observação em variáveis com as janelas Observação e Visualização Rápida.
Para inspecionar um valor de cadeia de caracteres, selecione Exibir (lupa) no lado direito da entrada Valor. Os tipos
str,unicode,bytesebytearrayestão disponíveis para inspeção.O menu suspenso Exibir exibe quatro opções de visualização: Texto, HTML, XML ou JSON.
Depois de selecionar uma visualização, uma caixa de diálogo pop-up mostra o valor da cadeia de caracteres sem aspas de acordo com o tipo selecionado. Você pode exibir a cadeia de caracteres com quebra automática e rolagem, realce de sintaxe e exibições em árvore. Essas visualizações podem ajudar a depurar problemas com cadeias de caracteres longas e complexas.
Ver exceções
Se ocorrer um erro no programa durante a depuração, mas você não tiver um manipulador de exceção para ele, o depurador quebra no ponto da exceção:
Quando ocorre um erro, você pode inspecionar o estado atual do programa, incluindo a pilha de chamadas. No entanto, se passar pelo código, o processo de depuração continuará a apresentar a exceção até que ela seja tratada ou o programa termine.
Para ver uma vista expandida das exceções, selecione Depurar>Windows>Configurações de Exceção.
Na janela Configurações de Exceções, a caixa de seleção ao lado de uma exceção controla se o depurador sempre quebra quando essa exceção é gerada.
Para quebrar com mais frequência para uma exceção específica, marque a caixa de seleção ao lado da exceção na janela Configurações de exceção.
Por padrão, a maioria das exceções é interrompida quando um manipulador de exceções não pode ser encontrado no código-fonte. Para alterar esse comportamento, clique com o botão direito do rato em qualquer exceção e modifique a opção Continuar Quando Não Tratado no Código do Utilizador. Para reduzir a frequência das interrupções causadas pela exceção, desmarque esta opção.
Para configurar uma exceção que não aparece na janela Configurações de exceção, selecione Adicionar (símbolo de adição). Insira um nome para a exceção a ser monitorizada. O nome deve corresponder ao nome completo da exceção.
Configurar opções de depuração de projeto
Por padrão, o depurador inicia seu programa com o iniciador Python padrão, sem argumentos de linha de comando e sem outros caminhos ou condições especiais. Você pode configurar as opções de inicialização para um projeto Python definindo as propriedades de depuração.
Para acessar as propriedades de depuração de um projeto, clique com o botão direito do mouse em seu projeto Python em Gerenciador de Soluções, selecione Propertiese, em seguida, selecione a guia Debug.
As seções a seguir descrevem as propriedades específicas.
Definir o comportamento de inicialização
A tabela a seguir lista os possíveis valores para a propriedade modo de inicialização do . Use essa propriedade para definir o comportamento de inicialização para o depurador.
Definir comportamento de execução
A tabela a seguir descreve as propriedades que você pode definir para configurar o comportamento de execução para o depurador.
| Propriedade | Descrição |
|---|---|
| Caminhos de Pesquisa | Especifique os caminhos de pesquisa de arquivo e pasta que o Visual Studio usa para seu projeto. Esses valores correspondem aos itens mostrados no nó Caminhos de Pesquisa do projeto no Explorador de Soluções . Embora você possa especificar caminhos de pesquisa nesta caixa de diálogo, pode ser mais fácil usar Gerenciador de Soluções, onde você pode procurar pastas e converter automaticamente caminhos em forma relativa. |
| Argumentos de script | Defina os argumentos a serem adicionados ao comando que o Visual Studio usa para iniciar o script e apareça após o nome do arquivo do script. O primeiro item listado no valor está disponível para seu script como sys.argv[1], o segundo como sys.argv[2]e assim por diante. |
| Argumentos do intérprete | Liste os argumentos a serem adicionados à linha de comando do iniciador antes do nome do script. Os argumentos comuns são -W ... para controlar avisos, -O para otimizar ligeiramente o programa e -u usar E/S sem buffer. É provável que os utilizadores do IronPython usem este campo para passar -X opções, como -X:Frames ou -X:MTA. |
| Caminho do Intérprete | Identifique um caminho de intérprete para substituir o caminho associado ao ambiente atual. O valor pode ser útil para iniciar o seu script com um intérprete não padrão. |
| Variáveis de ambiente | Use esta propriedade para adicionar entradas do formulário <NAME>=\<VALUE>. O Visual Studio aplica este valor de propriedade por último, sobre quaisquer variáveis de ambiente globais existentes, e depois que PYTHONPATH é configurado de acordo com a definição de Caminhos de Pesquisa . Como resultado, essa configuração pode ser usada para substituir manualmente qualquer uma dessas outras variáveis. |
Trabalhar com janelas interativas
Há duas janelas interativas de que podes usar durante uma sessão de depuração: a janela padrão do Visual Studio Immediate e a janela Python Debug Interactive.
Abrir a janela Imediata
Você pode usar a janela padrão do Visual Studio Immediate para avaliar rapidamente expressões Python e inspecionar ou atribuir variáveis em seu programa em execução. Para obter mais informações, consulte janela Immediate.
- Para abrir a janela Immediate, selecione Debug>Windows>Immediate. Você também pode usar o atalho de teclado Ctrl+Alt+I.
Abra a janela Debug Interactive
A janela Python Debug Interactive oferece um ambiente rico, disponibilizando toda a experiência de Interactive REPL durante a depuração, o que inclui escrever e executar código. Esta janela liga-se automaticamente a qualquer processo iniciado no depurador através do Inicializador Padrão do Python, incluindo processos anexados por meio de Debug>Attach to Process. No entanto, essa janela não está disponível ao usar depuração C/C++ de modo misto.
Para usar a janela Debug Interactive, selecione Debug>Windows>Python Debug Interactive (Shift+Alt+I).
A janela Debug Interactive suporta metacomandos especiais, além dos comandos REPL padrão , conforme descrito na tabela a seguir:
| Comando | Descrição |
|---|---|
$continue, $cont, $c |
Comece a executar o programa a partir da instrução atual. |
$down, $d |
Mova o quadro atual um nível para baixo no rastreamento de pilha. |
$frame |
Exiba o ID do quadro atual. |
$frame |
Mude o quadro atual para o quadro com o ID especificado. - Requer um argumento de ID de quadro <>. |
$load |
Carregue comandos do arquivo e execute até concluir. |
$proc |
Exiba a ID do processo atual. |
$proc |
Alterne o processo atual para a ID do processo especificada. - Requer um argumento ID do processo <>. |
$procs |
Liste os processos que estão sendo depurados no momento. |
$stepin, $step, $s |
Avance para a próxima chamada de função, se possível. |
$stepout, $return, $r |
Saia da função atual. |
$stepover, $until, $unt |
Passe sobre a próxima chamada de função. |
$thread |
Exiba o ID de thread atual. |
$thread |
Alterne o thread atual para o ID de thread especificado. - Requer um argumento de ID de thread <>. |
$threads |
Liste os threads que estão a ser depurados. |
$up, $u |
Mova o quadro atual um nível no rastreamento de pilha. |
$where, $w, $bt |
Liste os quadros para o tópico actual. |
As janelas padrão do depurador, como Processes, Threadse Call Stack não são sincronizadas com a janela Debug Interactive. Se você alterar o processo ativo, thread ou quadro na janela Debug Interactive, as outras janelas do depurador não serão afetadas. Da mesma forma, alterar o processo ativo, thread ou quadro nas outras janelas do depurador não afeta a janela Debug Interactive.
Usar o depurador herdado
Dependendo da configuração do seu ambiente, talvez seja necessário usar o depurador herdado:
- Visual Studio 2017 versão 15.7 e anterior com Python 2.6, 3.1 a 3.4 ou IronPython
- Visual Studio 2019 versão 16.5 e posterior com Python 2.6, 3.1 a 3.4 ou IronPython
- ptvsd 3.x e primeiras versões 4.x
O depurador herdado é o padrão no Visual Studio 2017 versão 15.7 e anterior.
- Para usar o depurador herdado, selecione Ferramentas>Opções, expanda Python>Debugging opções, e selecione a opção Usar depurador herdado.
Suporte a versões mais antigas do Visual Studio ou Python
O Visual Studio 2017 versão 15.8 e posterior usa um depurador baseado no ptvsd versão 4.1 e posterior. O Visual Studio 2019, versão 16.5 ou posterior, usa um depurador baseado em debugpy. Essas duas versões do depurador são compatíveis com Python 2.7 ou Python 3.5 e posterior.
Se você estiver executando uma dessas versões do Visual Studio, mas estiver usando Python 2.6, 3.1 a 3.4 ou IronPython, o Visual Studio mostrará o erro Depurador não oferece suporte a esse ambiente Python:
Quando o Visual Studio relata esse erro de ambiente, você deve usar o depurador herdado.
Suporta versões mais antigas do ptvsd
Se você estiver usando uma versão mais antiga do ptvsd no ambiente atual (como uma versão anterior 4.0.x ou uma versão 3.x necessária para depuração remota), o Visual Studio pode mostrar um erro ou aviso.
Se seu ambiente usa ptvsd 3.x, Visual Studio mostra o erro, pacote Depurador não pôde ser carregado:
O aviso, pacote do depurador está desatualizado, aparece quando você estiver usando uma versão 4.x anterior do ptvsd:
Quando o Visual Studio relata esses erros de ambiente, você deve usar o depurador herdado.
Importante
Embora você possa optar por ignorar o aviso para algumas versões do ptvsd, Visual Studio pode não funcionar corretamente.
Gerencie sua instalação do ptvsd
Siga estas etapas para gerenciar sua instalação do ptvsd:
Na janela Python Environments, vá para o separador Pacotes.
Digite ptvsd na caixa de pesquisa e examine a versão instalada do ptvsd:
Se a versão for inferior a 4.1.1a9 (a versão fornecida com o Visual Studio), selecione o X à direita do pacote para desinstalar a versão mais antiga. Em seguida, o Visual Studio usa sua versão empacotada. (Você também pode desinstalar do PowerShell usando o comando
pip uninstall ptvsd.)Como alternativa, você pode atualizar o pacote ptvsd para sua versão mais recente seguindo as instruções na seção Solucionar problemas de cenários de depuração.
Solucionar problemas de cenários de depuração
Os cenários a seguir descrevem outras opções de solução de problemas para a sua configuração de depuração.
Atualizar ptvsd para Visual Studio 2019
Se você tiver problemas com o depurador no Visual Studio 2019 versão 16.4 e anteriores, primeiro atualize sua versão do depurador da seguinte maneira:
Na janela Python Environments, vá para a aba Pacotes.
Digite ptvsd --upgrade na caixa de pesquisa e, em seguida, selecione comando executar: pip install ptvsd --upgrade. (Você também pode usar o mesmo comando do PowerShell.)
Se os problemas persistirem, registre um problema no repositório PTVS GitHub.
Observação
Para o Visual Studio 2019 versão 16.5 e versões posteriores, o debugpy faz parte do pacote Python do Visual Studio e é atualizado juntamente com o Visual Studio.
Ativar o registo do depurador
Durante a investigação de um problema do depurador, a Microsoft pode pedir que você habilite e colete logs do depurador para ajudar no diagnóstico.
Os passos seguintes ativam a depuração na sessão atual do Visual Studio:
Abra uma janela de comando no Visual Studio selecionando Ver>Outras Janelas>Janela de Comando.
Digite o seguinte comando:
DebugAdapterHost.Logging /On /OutputWindowComece a depurar e siga os passos necessários para reproduzir o seu problema. Durante este período, os logs de depuração aparecem na janela Output no Debug Adapter Host Log. Em seguida, você pode copiar os logs dessa janela e colar em um problema do GitHub, e-mail e assim por diante.
Se o Visual Studio parar de responder ou você não conseguir acessar a janela de saída do, reinicie o Visual Studio, abra uma janela de comando e digite o seguinte comando:
DebugAdapterHost.Logging /OnInicie a depuração e tente reproduzir o problema novamente. Os logs do depurador estão localizados em
%temp%\DebugAdapterHostLog.txt.
