Depuración remota de código de Python en Linux en Visual Studio

En este artículo, explorará cómo configurar la instalación de Visual Studio para admitir la depuración de código de Python en equipos Linux remotos. Este tutorial se basa en La versión 16.6 de Visual Studio 2019.

Visual Studio puede iniciar y depurar aplicaciones de Python de forma local y remota en un equipo Windows. Visual Studio también admite la depuración remota en un sistema operativo, dispositivo o implementación de Python diferente de CPython mediante la biblioteca de debugpy.

Visual Studio 2019, versión 16.4 y versiones anteriores, usa la biblioteca de ptvsd. En Visual Studio 2019, versión 16.5 y posteriores, la biblioteca debugpy reemplaza ptvsd. Cuando se usa debugpy, el código de Python que se depura hospeda el servidor de depuración al que Visual Studio puede asociar. Este hospedaje requiere una pequeña modificación en el código para importar y habilitar el servidor. También es posible que tenga que ajustar las configuraciones de red o firewall en el equipo remoto para permitir conexiones TCP.

Prerrequisitos

• Visual Studio instalado con compatibilidad con cargas de trabajo de Python. Para obtener más información, consulte Instalación de compatibilidad con Python en Visual Studio.

• Un equipo remoto que ejecuta Python en un sistema operativo como macOS o Linux.

• El puerto 5678 (entrante) está abierto en el firewall del ordenador remoto, que es el valor predeterminado para la depuración remota.

Configuración de un equipo Linux

Puede crear fácilmente una máquina virtual Linux de en Azure y acceder a ella mediante Escritorio Remoto desde Windows. Ubuntu para la máquina virtual es cómodo porque Python está instalado de forma predeterminada. Si tiene una configuración diferente, consulte Instalación de intérpretes de Python para otras ubicaciones de descarga de Python.

Configuración del firewall

El puerto de entrada 5678 debe estar abierto en el firewall del equipo remoto para permitir la depuración remota.

Para más información sobre cómo crear una regla de firewall para una máquina virtual de Azure, consulte los siguientes artículos:

• Filtrar el tráfico de red con un grupo de seguridad de red mediante Azure Portal
• Enrutamiento del tráfico de red con una tabla de rutas mediante Azure Portal
• Implementación y configuración de Azure Firewall mediante Azure Portal

Preparación del script para la depuración

Siga estos pasos para preparar un script para depurar el código de Python en Linux.

1. En el equipo remoto, cree un archivo de Python denominado guessing-game.py con el código siguiente:

   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 el paquete debugpy en el entorno mediante el comando pip3 install debugpy.

   Nota

   Es una buena idea grabar la versión de debugpy que está instalada en caso de que la necesite para solucionar problemas. La lista de debugpy también muestra las versiones disponibles.

3. Habilite la depuración remota agregando el código siguiente en la parte superior del archivo guessing-game.py antes de otro código. (Aunque no es un requisito estricto, es imposible depurar los subprocesos en segundo plano generados antes de llamar a la función listen).

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

4. Guarde el archivo y ejecute el programa:

   python3 guessing-game.py
   

   La llamada a la función listen se ejecuta en segundo plano y, mientras usted interactúa con el programa, espera las conexiones entrantes. Si quieres, puedes llamar a la función wait_for_client, después de llamar a la función listen, para bloquear el programa hasta que el depurador se conecte.

Sugerencia

Además de las funciones de listen y wait_for_client, debugpy también proporciona una función auxiliar breakpoint. Esta función actúa como un punto de interrupción programático si el depurador está conectado. Otra función, is_client_connected1, devuelve True si el depurador está asociado. No es necesario comprobar este resultado antes de llamar a cualquier otra función de debugpy.

Conectar remotamente desde Herramientas de Python

Los pasos siguientes muestran cómo establecer un punto de interrupción para detener el proceso remoto.

1. Cree una copia del archivo remoto en el equipo local y ábralo en Visual Studio. No importa dónde se encuentra el archivo, pero su nombre debe coincidir con el nombre del script en el equipo remoto.

2. (Opcional) Para tener IntelliSense para debugpy en su equipo local, instale el paquete debugpy en su entorno de Python.

3. Selecciona Depurar>Asociar al proceso.

4. En el cuadro de diálogo Asociar al proceso, establece Tipo de conexión en Depuración remota de Python (debugpy).

5. En el campo de destino de conexión , escriba el comando tcp://<ip_address>:5678.

   • tcp:// especifica el tipo de conexión como Protocolo de control de transmisión (TCP).
   • <ip_address> es la dirección IP del equipo remoto, que puede ser una dirección explícita o un nombre como myvm.cloudapp.net.
   • :5678 es el número de puerto de depuración remota.

6. Seleccione y presione para rellenar la lista de procesos de debugpy disponibles en ese equipo:

   

   Si ocurre que inicia otro programa en el equipo remoto después de rellenar esta lista, seleccione el botón Actualizar.

7. Selecciona el proceso que quieres depurar y selecciona Asociar, o haz doble clic en el proceso.

8. Visual Studio cambia al modo de depuración mientras el script continúa ejecutándose en el equipo remoto, lo que proporciona todas las capacidades habituales de depuración.

   Puedes establecer un punto de interrupción en la línea if guess < number:, después cambiar al equipo remoto y escribir otro intento. Visual Studio en el equipo local se detiene en el punto de interrupción, muestra variables locales, etc.

   

9. Al detener la depuración, Visual Studio se desconecta del programa. El programa continúa ejecutándose en el equipo remoto. debugpy también sigue escuchando para conectar depuradores, por lo que se puede volver a conectar al proceso en cualquier momento.

Resuelve problemas de conexión

Revise los siguientes puntos para ayudar a solucionar problemas con la conexión.

• Asegúrate de seleccionar Python remoto (debugpy) para Tipo de Conexión.

• Confirma que el secreto en Destino de la conexión coincide exactamente con el secreto en el código remoto.

• Confirme que la dirección IP en el objetivo de conexión coincide con la del equipo remoto.

• Comprueba que el puerto de depuración remota del equipo remoto esté abierto y que el destino de la conexión incluya el sufijo de puerto, como :5678.

  Para usar un puerto diferente, especifique el número de puerto de la llamada a la función listen, como en debugpy.listen((host, port)). En este caso, asegúrese de abrir el puerto específico en el firewall.

• Confirme que la versión debugpy instalada en el equipo remoto (tal como lo devuelve el comando pip3 list) coincide con la versión de Visual Studio Python Tools (PTVS).

  En la tabla siguiente se enumeran los pares de versión válidos. Según sea necesario, actualice la versión de debugpy en el equipo remoto.

  Visual Studio	Herramientas de Python	debugpy
  2019 16.6	1.0.0b5	1.0.0b5
  2019 16.5	1.0.0b1	1.0.0b1

Nota

Visual Studio 2019, versión 16.0-16.4, utiliza ptvsd, no debugpy. El proceso de este tutorial para esas versiones es similar, pero los nombres de función son diferentes. Visual Studio 2019 versión 16.5 usa debugpy, pero los nombres de función eran los mismos que los de ptvsd. En lugar de listen, usaría enable_attach. En lugar de wait_for_client, usaría wait_for_attach. En lugar de breakpoint, usaría break_into_debugger.

Uso de ptvsd 3.x para la depuración heredada

El depurador heredado ptvsd 3.x es el predeterminado en Visual Studio 2017, versión 15.7 y anteriores.

En función de la configuración de Visual Studio, es posible que debas utilizar ptvsd 3.x para la depuración remota.

• Visual Studio 2017, versión 15.7 y versiones anteriores con Python 2.6, 3.1 a 3.4 o IronPython
• Visual Studio 2019, versión 16.5 y posteriores, con Python 2.6, 3.1 a 3.4 o IronPython
• Versiones anteriores de la versión 4.x

Si la configuración implementa un escenario de versión anterior, Visual Studio muestra el error, Debugger no admite este entorno de Python.

Configuración de la depuración remota

A fin de prepararse para la depuración remota con ptvsd 3.x, completa los siguientes pasos:

1. Configure el secreto, que se usa para restringir el acceso al script en ejecución.

   En ptvsd 3.x, la función enable_attach requiere que pase un "secreto" como primer argumento.

   • Al conectar el depurador remoto, introduce el secreto con el comando enable_attach(secret="<secret>").

   Aunque puede permitir que cualquier usuario se conecte mediante el comando enable_attach(secret=None), no se recomienda esta opción.

2. Cree la dirección URL de destino de conexión con el formato tcp://<secret>@<ip_address>:5678.

   • tcp:// especifica el tipo de conexión como TCP.
   • <secret> es la cadena pasada con la función enable_attach en el código de Python.
   • <ip_address> es la dirección IP del equipo remoto, que puede ser una dirección explícita o un nombre como myvm.cloudapp.net.
   • :5678 es el número de puerto de depuración remota.

Conexión segura con el protocolo TCPS

De manera predeterminada, la conexión con el servidor de depuración remota de ptvsd 3.x está protegida solo mediante el secreto, y todos los datos se pasan en texto sin formato. Para una conexión más segura, ptvsd 3.x admite SSL mediante la forma segura del protocolo TCP o TCPS.

Siga estos pasos para configurar ptvsd 3.x para trabajar con el protocolo TCPS:

1. En el equipo remoto, use el comando openssl para generar archivos independientes para la clave y el certificado autofirmado:

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

   • En la solicitud de openssl, introduce el nombre de host o la dirección IP que utilizas para conectarte al Nombre común.

   Para obtener más información, consulte Certificados autofirmados en la documentación del módulo Python ssl. Tenga en cuenta que el comando descrito en la documentación de Python genera solo un único archivo combinado.

2. En el código, modifique la llamada a la función enable_attach para incluir certfile y keyfile argumentos mediante los nombres de archivo como valores. Estos argumentos tienen el mismo significado que para la función estándar ssl.wrap_socket Python.

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

   También puede realizar el mismo cambio en el archivo de código en el equipo local. Dado que este código no se ejecuta realmente, no es estrictamente necesario.

3. Reinicia el programa de Python en el equipo remoto a fin de que esté listo para la depuración.

4. Proteja el canal agregando el certificado a la CA de raíz de confianza en el equipo Windows con Visual Studio:

   1. Copie el archivo de certificado del equipo remoto en el equipo local.

   2. Abre Panel de control y ve a Herramientas de Windows>Administrar certificados del equipo.

   3. En el cuadro de diálogo certlm [Certificados - equipo local], expande el nodo Entidades de certificación raíz de confianza, haz clic con el botón derecho en Certificados y selecciona Todas las tareas>Importar.

   4. Navega al archivo .cer copiado desde el equipo remoto y selecciónalo.

   5. Continúe con las indicaciones del cuadro de diálogo para completar el proceso de importación.

5. Repita el proceso de asociación en Visual Studio, como se ha descrito anteriormente en Asociar de forma remota desde Herramientas de Python.

   Para esta instancia, define tcps:// como el protocolo para el Destino de la conexión (o Calificador).

   

Solucionar problemas de conexión

Durante el intento de conexión, Visual Studio podría encontrar problemas. Revise los siguientes escenarios y realice las acciones adecuadas, según sea necesario.

• Visual Studio advierte sobre posibles problemas de certificado al conectarse a través de SSL.

  Acción: puede omitir el mensaje y continuar.

  Cautela

  Tenga en cuenta que, aunque el canal todavía está cifrado contra la interceptación, podría ser susceptible a ataques de intermediario.

• Visual Studio muestra la advertencia de que el certificado remoto no es de confianza.

  Problema: el certificado no se agrega correctamente a la CA raíz de confianza.

  Acción: comprueba de nuevo los pasos para agregar el certificado a la CA raíz de confianza en el equipo Windows y vuelve a intentar la conexión.

  

• Visual Studio muestra la advertencia de que el nombre del certificado remoto no coincide con el nombre de host.

  Problema: no se especifica el nombre de host o la dirección IP adecuados para el nombre común para el certificado.

  Acción: vuelva a comprobar los pasos descritos en Proteger la conexión con TCPS. Asegúrese de usar el nombre común correcto al crear el certificado e intente la conexión nuevamente.

  

Contenido relacionado

• Depuración remota