Partilhar via

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

Neste artigo, você explora como configurar sua instalação do Visual Studio para oferecer 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 oferece suporte à depuração remotamente em um sistema operacional, dispositivo ou implementação Python diferente do CPython usando a biblioteca de depuração .

O Visual Studio 2019 versão 16.4 e anteriores usa a biblioteca ptvsd . Em Visual Studio 2019 versão 16.5 e posteriores, a biblioteca debugpy substitui o ptvsd. Quando se utiliza o debugpy, o código Python que está a ser depurado hospeda o servidor de depuração ao qual o Visual Studio pode se conectar. Esta hospedagem requer uma pequena modificação no seu código para importar e habilitar o servidor. Também pode ser necessário 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 Python. Para obter mais informações, consulte Instalar suporte a Python no Visual Studio.

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

  • A porta 5678 (de entrada) está aberta no firewall do computador remoto, sendo esta a configuração padrão para a depuração remota.

Configurar um computador Linux

Você pode criar facilmente uma máquina virtual Linux no Azure e acessá-la usando a Área de Trabalho Remota do Windows. Ubuntu para a máquina virtual é conveniente porque Python é instalado por padrão. Se você tiver uma configuração diferente, consulte Instalar interpretadores 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 permitir a depuração remota.

Para obter detalhes sobre como criar uma regra de firewall para uma máquina virtual do Azure, consulte os seguintes artigos:

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.

    Observação

    É uma boa ideia gravar a versão do debugpy que está instalada, caso você precise dela para solução de problemas. A listagem de 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 quaisquer 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. Se desejar, pode chamar a função wait_for_client depois de chamar a função listen para bloquear o programa até que o depurador esteja ligado.

Dica

Além das funções listen e wait_for_client, o debugpy também fornece uma função auxiliar breakpoint. Esta função atua como um ponto de interrupção programático se o depurador estiver ligado. Outra função, is_client_connected1, retorna True se o depurador estiver ligado. Não é necessário verificar este resultado antes de chamar qualquer outra função debugpy.

Anexar remotamente a partir de Ferramentas 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 o debugpy no seu computador local, instale o pacote debugpy no seu ambiente Python.

  3. Selecione Depurar>Anexar ao processo.

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

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

    • tcp:// especifica o tipo de conexão como TCP (Transmission Control Protocol).
    • <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 preencher a lista de processos de depuração disponíveis nesse computador:

    Captura de ecrã que mostra como inserir o destino da conexão para ver uma lista de processos debugpy disponíveis.

    Se acontecer de você iniciar outro programa no computador remoto depois de preencher essa lista, selecione o botão Atualizar.

  7. Selecione o processo a ser depurado e selecione Anexarou 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 usuais de de depuração de.

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

    Captura de tela que mostra como o Visual Studio pausa a depuração quando um ponto de interrupção é atingido.

  9. Quando você para de depurar, o Visual Studio se desanexa do programa. O programa continua a ser executado no computador remoto. debugpy também continua escutando para anexar depuradores, para que você possa reanexar ao processo novamente a qualquer momento.

Solucionar problemas de conexão

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

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

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

  • Confirme se o endereço IP no Connection Target corresponde ao do computador remoto.

  • Verifique se a porta de depuração remota no computador remoto está aberta e que o alvo da conexão inclua o sufixo da 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, certifique-se de abrir 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ões válidos. Conforme necessário, atualize a versão do debugpy no computador remoto.

    Estúdio Visual Ferramentas 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. Visual Studio 2019, a versão 16.5, usa debugpy, mas os nomes das funções são os mesmos que no 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.

Utilize 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 anteriores.

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
  • Primeiras versões 4.x

Se sua configuração implementa um cenário de versão mais antiga, o Visual Studio mostra o erro, Depurador não suporta esse ambiente Python.

Configurar depuração remota

Para se preparar para a depuração remota com o 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 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 o URL de destino da conexão no formato tcp://<secret>@<ip_address>:5678.

    • tcp:// especifica o tipo de conexão como TCP.
    • <secret> é a string 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 para 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 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 suporta 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 de openssl, digite o nome do host ou endereço IP que utiliza 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 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 dos arquivos 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 esteja pronto para depuração.

  4. Proteja o canal adicionando o certificado à 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 Painel de Controle e vá para 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 em Certificados e selecione Todas as Tarefas >Importar.

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

    5. Continue pelos 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 do Python Tools.

    Para este exemplo, defina tcps:// como o protocolo para o alvo de conexão (ou o qualificador ).

    Captura de ecrã que mostra como especificar TCPS como transporte de depuração remota com SSL.

Resolver problemas de ligação

Durante a tentativa de conexão, o Visual Studio pode encontrar problemas. Analise os cenários a seguir e tome as medidas apropriadas, conforme necessário.

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

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

    Atenção

    Tenha em mente que, embora o canal ainda esteja criptografado contra interceptação, ele pode estar aberto a ataques de intermediário.

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

    Problema: O certificado não foi 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 Windowse tente a conexão novamente.

    Captura de tela do aviso que diz que o certificado SSL remoto não é confiável.

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

    Problema: O nome de host ou endereço IP adequado não é especificado para o Nome Comum do certificado.

    Ação: Revise as etapas em Securizar a conexão com TCPS. Certifique-se de usar o nome comum correto quando criar o certificado, e tente a conexão novamente.

    Captura de tela do aviso que diz que o certificado SSL remoto não corresponde ao nome do host.

Conteúdo relacionado

  • Last updated on