Depurar remotamente o código Python no Linux no Visual Studio

Neste artigo, você explora como configurar a instalação do Visual Studio para dar suporte à depuração de código Python em computadores Linux remotos. Este passo a passo é baseado no Visual Studio 2019 versão 16.6.

O Visual Studio pode iniciar e depurar aplicativos Python local e remotamente em um computador Windows. O Visual Studio também dá suporte à depuração também pode depurar remotamente em um dispositivo ou sistema operacional diferente ou em uma implementação Python que não seja o CPython usando a biblioteca debugpy.

O Visual Studio 2019 versão 16.4 e anterior usa a biblioteca ptvsd. No Visual Studio 2019 versão 16.5 e posterior, a biblioteca debugpy substitui a ptvsd. Quando você usa a debugpy, o código do Python que está sendo depurado hospeda o servidor de depuração ao qual o Visual Studio pode se anexar. Essa hospedagem exige uma pequena modificação no seu código para importar e habilitar o servidor. Talvez também seja preciso ajustar as configurações de rede ou firewall no computador remoto para permitir as conexões TCP.

Pré-requisitos

• Ter o Visual Studio instalado e compatível com cargas de trabalho do Python. Para obter mais informações, confira Instalar o suporte ao Python no Visual Studio.

• Um computador remoto que execute o Python em um sistema operacional como o Mac OSX ou Linux.

• A porta 5678 (entrada) abre no firewall desse computador remoto, que é o padrão para a depuração remota.

Configurar um computador Linux

Crie com facilidade uma máquina virtual do Linux no Azure e acesse-a usando a Área de Trabalho Remota no Windows. O Ubuntu para a máquina virtual é conveniente porque o Python é instalado por padrão. Se você tiver outra configuração, consulte Instalar interpretadores do Python para outros locais de download do Python.

Configurar o firewall

A porta de entrada 5678 deve estar aberta no firewall do computador remoto para dar suporte à depuração remota.

Para ver em detalhes como criar uma regra de firewall para uma máquina virtual do Azure, consulte estes artigos:

• Filtrar tráfego de rede com um grupo de segurança de rede usando o Portal do Azure
• Rotear tráfego com uma tabela de rotas utilizando o Portal do Azure
• Implantar e configurar o Firewall do Azure usando o portal do Azure

Preparar o script para depuração

Siga estes passos para preparar um script para depurar seu código Python no Linux.

1. No computador remoto, crie um arquivo do Python chamado guessing-game.py com este código:

   import random
   
   guesses_made = 0
   name = input('Hello! What is your name?\n')
   number = random.randint(1, 20)
   print('Well, {0}, I am thinking of a number between 1 and 20.'.format(name))
   
   while guesses_made < 6:
       guess = int(input('Take a guess: '))
       guesses_made += 1
       if guess < number:
           print('Your guess is too low.')
       if guess > number:
           print('Your guess is too high.')
       if guess == number:
           break
   if guess == number:
       print('Good job, {0}! You guessed my number in {1} guesses!'.format(name, guesses_made))
   else:
       print('Nope. The number I was thinking of was {0}'.format(number))
   

2. Instale o pacote debugpy no ambiente usando o comando pip3 install debugpy.

   Observação

   É recomendável gravar a versão do debugpy que está instalada caso você precise dela para solução de problemas. A listagem debugpy também mostra as versões disponíveis.

3. Habilite a depuração remota adicionando o seguinte código na parte superior do arquivo guessing-game.py antes de outro código. (Embora esse não seja um requisito estrito, é impossível depurar os threads em segundo plano gerados antes que a função listen seja chamada.)

   import debugpy
   debugpy.listen(('0.0.0.0', 5678))
   

4. Salve o arquivo e execute o programa:

   python3 guessing-game.py
   

   A chamada para a função listen é executada em segundo plano e aguarda as conexões de entrada enquanto você interage com o programa de outra maneira. Se quiser, você pode chamar a função wait_for_client depois de chamar a função listen para bloquear o programa até que o depurador seja anexado.

Dica

Além das funções listen e wait_for_client, o debugpy também fornece uma função breakpoint. Essa função serve como ponto de interrupção programático se o depurador estiver conectado. Outra função, is_client_connected1, retorna True se o depurador for anexado. Você não precisa verificar esse resultado antes de chamar outras funções debugpy.

Anexar remotamente por meio das Ferramentas Python

Os passos a seguir mostram como definir um ponto de interrupção para interromper o processo remoto.

1. Crie uma cópia do arquivo remoto no computador local e abra-a no Visual Studio. Não importa a localização do arquivo, mas o nome deve corresponder ao nome do script no computador remoto.

2. (Opcional) Para ter o IntelliSense para debugpy no computador local, instale o pacote de debugpy em seu ambiente de Python.

3. Selecione Depurar>Anexar ao Processo.

4. Na caixa de diálogo Anexar ao processo, defina Tipo de conexão como Python remoto (debugpy).

5. No campo Destino da conexão, insira o comando tcp://<ip_address>:5678.

   • O tcp:// especifica o tipo de conexão como Protocolo TCP (protocolo de controle de transmissão).
   • <ip_address> é o endereço IP do computador remoto; ele pode ser um endereço explícito ou um nome como myvm.cloudapp.net.
   • :5678 é o número da porta de depuração remota.

6. Selecione Enter para popular a lista de processos do debugpy disponíveis nesse computador:

   

   Se outro programa for iniciado no computador remoto após a lista ser populada, selecione o botão Atualizar.

7. Selecione o processo a ser depurado e selecione Anexar ou clique duas vezes no processo.

8. Então, o Visual Studio alternará para o modo de depuração enquanto o script continuará a ser executado no computador remoto, fornecendo todos os recursos normais de depuração.

   Você pode definir um ponto de interrupção na linha if guess < number: e, em seguida, mude para o computador remoto e insira outra tentativa. O Visual Studio do seu computador local parará no ponto de interrupção, mostrará variáveis locais e assim por diante:

   

9. Quando você parar de depurar, o Visual Studio irá se desanexar do programa. O programa continua sendo executado no computador remoto. O debugpy também continua a escuta para anexar depuradores, assim, é possível anexá-los novamente ao processo a qualquer momento.

Solucionar problemas de conexão

Analise os seguintes pontos para ajudar a solucionar problemas com a conexão.

• Certifique-se de selecionar Python remota (debugpy) para Tipo de Conexão

• Confirme que o segredo no Destino de Conexão corresponde exatamente ao segredo no código remoto.

• Confirme o endereço IP no Destino de Conexão corresponde ao do computador remoto.

• Verifique se a porta de depuração remota do computador remoto está aberta e se o destino da conexão inclui o sufixo da porta, como :5678.

  Para usar outra porta, especifique o número da porta na chamada para a função listen, como em debugpy.listen((host, port)). Nesse caso, certifique-se de abrir a porta específica no firewall.

• Confirme se a versão de depuração instalada no computador remoto (conforme retornado pelo comando pip3 list) corresponde à versão do Visual Studio Python Tools (PTVS).

  A tabela a seguir lista os pares de versões válidos. Conforme necessário, atualize no computador remoto a versão do debugpy.

  Visual Studio	Ferramentas do Python	debugpy
  2019 16.6	1.0.0b5	1.0.0b5
  2019 16.5	1.0.0b1	1.0.0b1

Observação

O Visual Studio 2019 versão 16.0-16.4 utilizou ptvsd, não debugpy. O processo neste passo a passo para essas versões é semelhante, mas os nomes das funções são diferentes. O Visual Studio 2019 versão 16.5 usa depuração, mas os nomes de função eram iguais aos do ptvsd. Em vez de listen, você usaria enable_attach. Em vez de wait_for_client, você usaria wait_for_attach. Em vez de breakpoint, você usaria break_into_debugger.

Usar ptvsd 3.x para depuração herdada

O depurador herdado do ptvsd 3.x é o padrão no Visual Studio 2017 versão 15.7 e anterior.

Dependendo da configuração do Visual Studio, talvez seja preciso usar o ptvsd 3.x para depuração remota:

• O Visual Studio 2017 versão 15.7 e anterior com Python 2.6, 3.1 a 3.4 ou IronPython
• O Visual Studio 2019 versão 16.5 e posterior com Python 2.6, 3.1 a 3.4 ou IronPython
• Versões 4.x anteriores

Se sua configuração implementar um cenário de versão mais antiga, o Visual Studio mostrará o erro, O depurador não dá suporte a este ambiente do Python.

Configurar depuração remota

Para se preparar para a depuração remota com o ptvsd 3.x, siga estes passos:

1. Configure seu segredo, que é usado para restringir acesso ao script em execução.

   No ptvsd 3.x, a função enable_attach requer que você passe um "segredo" como o primeiro argumento.

   • Ao anexar o depurador remoto, insira o segredo com o comando enable_attach(secret="<secret>").

   Embora você possa permitir que qualquer pessoa se conecte usando o comando enable_attach(secret=None), essa opção não é recomendada.

2. Crie a sua URL de destino de conexão no formato tcp://<secret>@<ip_address>:5678.

   • tcp:// especifica o tipo de conexão como TCP.
   • <secret> é a cadeia de caracteres passada com a função enable_attach no código Python.
   • <ip_address> é o endereço IP do computador remoto; ele pode ser um endereço explícito ou um nome como myvm.cloudapp.net.
   • :5678 é o número da porta de depuração remota.

Conexão segura com protocolo TCPS

Por padrão, a conexão com o servidor de depuração remota ptvsd 3.x é protegida somente pelo segredo e todos os dados são passados em texto sem formatação. Para uma conexão mais segura, o ptvsd 3.x dá suporte a SSL usando a forma segura do protocolo TCP ou TCPS.

Use estes passos para configurar o ptvsd 3.x para funcionar com o protocolo TCPS:

1. No computador remoto, use o comando openssl para gerar arquivos separados para a chave e o certificado autoassinado:

   openssl req -new -x509 -days 365 -nodes -out cert.cer -keyout cert.key
   

   • No prompt, openssl digite o nome do host ou o endereço IP que você usa para se conectar ao Nome comum.

   Para obter mais informações, consulte Certificados autoassinados na documentação do módulo Python ssl. Observe que o comando descrito na documentação do Python gera somente um único arquivo combinado.

2. No código, modifique a chamada para a função enable_attach para incluir os argumentos certfile e keyfile usando os nomes de arquivos como os valores. Esses argumentos têm o mesmo significado que para a função Python padrão ssl.wrap_socket.

   ptvsd.enable_attach(secret='my_secret', certfile='cert.cer', keyfile='cert.key')
   

   Você também pode fazer a mesma modificação no arquivo de código no computador local. Como esse código não é executado, ele não é estritamente necessário.

3. Reinicie o programa de Python no computador remoto para que fique pronto para depuração.

4. Proteja o canal adicionando o certificado à AC Raiz Confiável no computador Windows com o Visual Studio:

   1. Copie o arquivo de certificado do computador remoto para o computador local.

   2. Abra o Painel de Controle e acesse Ferramentas do Windows>Gerenciar certificados de computador.

   3. Na caixa de diálogo certlm [Certificados - computador local], expanda o nó Autoridades de Certificação Confiáveis, clique com o botão direito em Certificados e selecione Todas as tarefas>Importar.

   4. Procure e selecione o arquivo .cer copiado do computador remoto.

   5. Continue pelos prompts da caixa de diálogo para concluir o processo de importação.

5. Repita o processo de anexação no Visual Studio, como descrito anteriormente em Anexar remotamente por meio das Ferramentas Python.

   Para este caso, defina tcps:// como o protocolo para o Destino da conexão (ou Qualificador).

   

Resolver os problemas de conexão

Ao tentar a conexão, o Visual Studio pode encontrar problemas. Analise os cenários a seguir e aplique a ação apropriada, conforme necessário.

• O Visual Studio avisa sobre possíveis problemas de certificado ao se conectar via SSL.

  Ação: você pode ignorar a mensagem e continuar.

  Cuidado

  Lembre-se de que, embora o canal ainda esteja criptografado contra espionagem, ele pode estar aberto a ataques de man-in-the-middle.

• O Visual Studio exibe o aviso de certificado remoto não confiável.

  Problema: o certificado não foi adicionado corretamente à AC de Raiz Confiável.

  Ação: verifique novamente os passos para adicionar o certificado à AC de Raiz Confiável no computador Windows e tente a conexão novamente.

  

• O Visual Studio mostra o aviso O nome do certificado remoto não corresponde ao nome do host.

  Problema: o nome de host ou endereço IP apropriado não está especificado para o Nome comum do certificado.

  Ação: verifique novamente os passos em Proteger a conexão com TCPS. Certifique-se de usar o Nome comum correto ao criar o certificado e tente a conexão novamente.

  

Conteúdo relacionado

• Depuração remota