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

Neste artigo, você explorará como configurar sua instalação do Visual Studio para dar suporte à depuração do 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 de maneira remota em um sistema operacional, dispositivo ou implementação do Python que não seja o CPython usando a biblioteca de depuração.

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

Pré-requisitos

• Visual Studio instalado com suporte para cargas de trabalho do Python. Para obter mais informações, consulte Instalar o suporte ao Python no Visual Studio.

• Um computador remoto executando o Python em um sistema operacional como macOS ou Linux.

• A porta 5678 (entrada) está aberta no firewall do computador remoto, que é o padrão para depuração remota.

Configurar um computador Linux

Você pode criar facilmente uma máquina virtual Linux no Azure e acessá-la usando Área de Trabalho Remota do Windows. O Ubuntu para a máquina virtual é conveniente porque o Python está instalado por padrão. Se você tiver uma configuração diferente, 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 obter detalhes sobre como criar uma regra de firewall para uma máquina virtual do Azure, consulte os seguintes artigos:

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

Preparar o script para depuração

Siga estas etapas para preparar um script para depurar seu código Python no Linux.

1. No computador remoto, crie um arquivo Python chamado guessing-game.py com o seguinte 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 em seu ambiente usando o comando pip3 install debugpy.

   Nota

   É uma boa ideia registrar a versão do debugpy instalada, em caso de necessidade para solucionar problemas. A listagem do debugpy também mostra as versões disponíveis.

3. Habilite a depuração remota adicionando o código a seguir na parte superior do arquivo guessing-game.py antes de outro código. (Embora 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 conexões de entrada à medida que você interage com o programa. Se desejar, você poderá chamar a função wait_for_client depois de chamar a função listen para bloquear o programa até que o depurador se conecte.

Dica

Além das funções listen e wait_for_client, o debugpy também oferece uma função auxiliar breakpoint. Essa função serve como um ponto de interrupção de programação se o depurador estiver conectado. Outra função, is_client_connected1, retornará True se o depurador estiver ativo. Você não precisa verificar esse resultado antes de chamar outras funções de debugpy.

Anexar remotamente a partir das Ferramentas do Python

As etapas 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-o no Visual Studio. Não importa onde o arquivo está localizado, mas seu nome deve corresponder ao nome do script no computador remoto.

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

3. Selecione Depurar>Anexar ao Processo.

4. No diálogo Anexar ao Processo, configure o Tipo de Conexão como Python remoto (debugpy).

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

   • tcp:// especifica o tipo de conexão como Protocolo de Controle de Transmissão (TCP).
   • <ip_address> é o endereço IP do computador remoto, que 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 você iniciar outro programa no computador remoto depois de preencher essa lista, selecione o botão Atualizar.

7. Selecione o processo para depurar e selecione Anexar ou clique duas vezes no processo.

8. O Visual Studio alterna para o modo de depuração enquanto o script continua a ser executado no computador remoto, fornecendo todos os recursos de depuração comuns .

   Você pode definir um ponto de interrupção na linha if guess < number:, depois alternar para o computador remoto e inserir outro palpite. O Visual Studio no computador local para no ponto de interrupção, mostra variáveis locais e assim por diante:

   

9. Quando você interrompe a depuração, o Visual Studio se desconecta 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

Examine os pontos a seguir para ajudar a solucionar problemas com a conexão.

• Selecione Remota do Python (debugpy) para o Tipo de Conexão.

• Confirme se o segredo no destino de conexão corresponde exatamente ao segredo no código remoto.

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

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

  Para usar uma porta diferente, especifique o número da porta na chamada para a função listen, como em debugpy.listen((host, port)). Nesse caso, abra a porta específica no firewall.

• Confirme se a versão do debugpy 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ão válidos. Conforme necessário, atualize a versão do debugpy no computador remoto.

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

Nota

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 de função são diferentes. O Visual Studio 2019 versão 16.5 usa debugpy, mas os nomes de função eram os mesmos 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.

Use o ptvsd 3.x para depuração herdada

O depurador herdado 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 necessário usar o ptvsd 3.x para depuração remota:

• 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
• Versões iniciais do 4.x

Se sua configuração implementar um cenário de versão mais antigo, o Visual Studio mostrará o erro Depurador não oferece suporte a esse ambiente Python.

Configurar depuração remota

Para se preparar para depuração remota com ptvsd 3.x, conclua as seguintes etapas:

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

   No ptvsd 3.x, a função enable_attach exige 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 sua URL de destino de conexão no formulário 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, que 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 o protocolo TCPS

Por padrão, a conexão com o servidor de depuração remota ptvsd 3.x é protegida apenas 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 as seguintes etapas para configurar o ptvsd 3.x para trabalhar 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, insira 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 ssl do Python. Observe que o comando descrito na documentação do Python gera apenas um único arquivo combinado.

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

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

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

3. Reinicie o programa Python no computador remoto para que ele esteja pronto para depuração.

4. Proteja o canal adicionando o certificado à AC (Autoridade de Certificação) 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 Raiz Confiáveis, clique com o botão direito do mouse em Certificados e selecione Todas as Tarefas>Importar.

   4. Navegue até e selecione o arquivo .cer copiado do computador remoto.

   5. Continue por meio dos prompts de diálogo para concluir o processo de importação.

5. Repita o processo de anexação no Visual Studio, conforme descrito anteriormente em Anexar remotamente a partir das Ferramentas Python.

   Para esta instância, defina tcps:// como o protocolo para o Destino de Conexão (ou Qualificador).

   

Resolver problemas de conexão

Durante a tentativa de conexão, o Visual Studio pode encontrar problemas. Examine os cenários a seguir e execute a ação apropriada, conforme necessário.

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

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

  Cuidado

  Tenha em mente que, embora o canal ainda esteja criptografado contra espionagem, ele pode estar aberto a ataques do tipo man-in-the-middle.

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

  Problema: o certificado não é adicionado corretamente à autoridade de certificação raiz confiável.

  Ação: verifique novamente as etapas para adicionar o certificado à autoridade de certificação raiz confiável no computador Windows e tente a conexão novamente.

  

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

  Problema: o nome do host ou endereço IP adequado não está especificado para o Nome Comum para o certificado.

  Ação: verifique novamente as etapas em Proteger a conexão com o 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