Déboguer à distance du code Python sur Linux dans Visual Studio

Dans cet article, vous découvrirez comment configurer votre installation de Visual Studio pour prendre en charge le débogage du code Python sur des ordinateurs Linux distants. Cette procédure pas à pas est basée sur Visual Studio 2019 version 16.6.

Visual Studio peut lancer et déboguer des applications Python localement et à distance sur un ordinateur Windows. Visual Studio prend également en charge le débogage à distance sur un système d’exploitation, un appareil ou une implémentation Python différente de CPython en utilisant la bibliothèque debugpy.

Visual Studio 2019 version 16.4 et et les versions antérieures utilisent la bibliothèque ptvsd. Dans Visual Studio 2019 version 16.5 et les versions ultérieures, la bibliothèque debugpy remplace ptvsd. Lorsque vous utilisez debugpy, le code Python en cours de débogage héberge le serveur de débogage auquel Visual Studio peut se connecter. Cet hébergement nécessite une petite modification de votre code pour importer et activer le serveur. Vous devrez peut-être également ajuster les configurations réseau ou pare-feu sur l’ordinateur distant pour autoriser les connexions TCP.

Prérequis

• Visual Studio installé avec le support pour les charges de travail Python. Pour plus d’informations, veuillez consulter la rubrique Installer le support Python dans Visual Studio.

• Un ordinateur distant exécutant Python sur un système d’exploitation Mac OSX ou Linux.

• Le port 5678 (entrant) doit être ouvert sur le pare-feu de l’ordinateur distant, ce qui est la valeur par défaut pour le débogage à distance.

Configurer un ordinateur Linux

Vous pouvez facilement créer une machine virtuelle Linux sur Azure et y accéder en utilisant Bureau à distance depuis Windows. Ubuntu pour la machine virtuelle est pratique car Python est installé par défaut. Si vous avez une configuration différente, veuillez consulter la rubrique Installer des interpréteurs Python pour d’autres emplacements de téléchargement Python.

Configurer le pare-feu

Le port entrant 5678 doit être ouvert sur le pare-feu de l’ordinateur distant pour prendre en charge le débogage à distance.

Pour des détails sur la création d’une règle de pare-feu pour une machine virtuelle Azure, veuillez consulter les articles suivants :

• Filtrer le trafic réseau avec un groupe de sécurité réseau en utilisant le portail Azure
• Acheminer le trafic réseau avec une table de routage à l’aide du portail Azure
• Déployer et configurer un pare-feu Azure à l’aide du portail Azure

Préparer le script pour le débogage

Suivez ces étapes pour préparer un script pour déboguer votre code Python sur Linux.

1. Sur l’ordinateur distant, créez un fichier Python nommé guessing-game.py avec le code suivant :

   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. Installez le package debugpy dans votre environnement en utilisant la commande pip3 install debugpy.

   Remarque

   Il est judicieux d’enregistrer la version de debugpy qui est installée au cas où vous en auriez besoin pour le dépannage. La liste debugpy montre également les versions disponibles.

3. Activez le débogage à distance en ajoutant le code suivant en haut du fichier guessing-game.py avant tout autre code. (Bien que cela ne soit pas strictement nécessaire, il est impossible de déboguer des threads en arrière-plan générés avant que la fonction listen ne soit appelée.)

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

4. Enregistrez le fichier et exécutez le programme :

   python3 guessing-game.py
   

   L’appel à la fonction listen s’exécute en arrière-plan et attend les connexions entrantes pendant que vous interagissez avec le programme. Si nécessaire, vous pouvez appeler la fonction wait_for_client après avoir appelé la fonction listen pour bloquer le programme jusqu’à ce que le débogueur se connecte.

Conseil

En plus des fonctions listen et wait_for_client, debugpy fournit également une fonction d’aide breakpoint. Cette fonction sert de point d’arrêt programmable si le débogueur est connecté. Une autre fonction, is_client_connected1, renvoie True si le débogueur est connecté. Vous n’avez pas besoin de vérifier ce résultat avant d’appeler d’autres fonctions debugpy.

Attacher à distance à partir de Python Tools

Les étapes suivantes montrent comment définir un point d’arrêt pour arrêter le processus distant.

1. Créez une copie du fichier distant sur l’ordinateur local et ouvrez-le dans Visual Studio. L’emplacement du fichier importe peu, mais son nom doit correspondre au nom du script sur l’ordinateur distant.

2. (Facultatif) Pour activer la fonctionnalité IntelliSense pour debugpy sur l’ordinateur local, installez le package debugpy dans votre environnement Python.

3. Sélectionnez Déboguer>Attacher au processus.

4. Dans la boîte de dialogue Joindre au processus, paramétrez Type de connexion sur Python à distance (debugpy).

5. Dans le champ Cible de connexion, saisissez la commande tcp://<ip_address>:5678.

   • tcp:// spécifie le type de connexion en tant que protocole de contrôle de transmission (TCP).
   • <ip_address> est l’adresse IP de l’ordinateur distant, qui peut être une adresse explicite ou un nom comme monvm.cloudapp.net.
   • :5678 est le numéro de port de débogage à distance.

6. Sélectionnez Entrée pour afficher la liste des processus debugpy disponibles sur cet ordinateur :

   

   Si vous démarrez un autre programme sur l’ordinateur distant après avoir rempli cette liste, sélectionnez le bouton Actualiser.

7. Sélectionnez le processus à déboguer et sélectionnez Attacher, ou double-cliquez sur le processus.

8. Visual Studio passe en mode de débogage pendant que le script continue de s’exécuter sur l’ordinateur distant, offrant toutes les fonctionnalités de débogage habituelles.

   Vous pouvez définir un point d’arrêt sur la ligne if guess < number:, puis passer à l’ordinateur distant et entrer une autre supposition. Visual Studio sur votre ordinateur local s’arrête au point d’arrêt, affiche les variables locales, etc. :

   

9. Lorsque vous arrêtez le débogage, Visual Studio se détache du programme. Le programme continue de s’exécuter sur l’ordinateur distant. debugpy poursuit également l’écoute des attachements de débogueurs, pour vous permettre de rattacher le processus à tout moment.

Résoudre les problèmes de connexion

Examinez les points suivants pour aider à dépanner les problèmes de connexion.

• Assurez-vous de sélectionner Python à distance (debugpy) pour le Type de connexion.

• Confirmez que le secret dans la Cible de connexion correspond exactement au secret dans le code distant.

• Confirmez que l’adresse IP dans la Cible de connexion correspond à celle de l’ordinateur distant.

• Vérifiez que le port de débogage à distance sur l’ordinateur distant est ouvert, et que la cible de connexion inclut le suffixe du port, tel que :5678.

  Pour utiliser un port différent, spécifiez le numéro de port dans l’appel à la fonction listen, comme dans debugpy.listen((host, port)). Dans ce cas, assurez-vous d’ouvrir le port spécifique dans le pare-feu.

• Vérifiez que la version de debugpy installée sur l’ordinateur distant (telle que retournée par la commande pip3 list) correspond à la version de Virtual Studio Python Tools (PTVS).

  Le tableau suivant répertorie les paires de versions valides. Si nécessaire, mettez à jour la version de debugpy sur l’ordinateur distant.

  Visual Studio	Outils Python	debugpy
  2019 16.6	1.0.0b5	1.0.0b5
  2019 16.5	1.0.0b1	1.0.0b1

Notes

Visual Studio 2019 version 16.0-16.4 utilisait ptvsd, et non pas debugpy. Le processus de cette procédure pas à pas pour ces versions est similaire, mais les noms de fonction sont différents. Visual Studio 2019 version 16.5 utilise debugpy, mais les noms des fonctions étaient les mêmes que dans ptvsd. Au lieu de listen, vous utiliseriez enable_attach. Au lieu de wait_for_client, vous utiliseriez wait_for_attach. Au lieu de breakpoint, vous utiliseriez break_into_debugger.

Utilisez ptvsd 3.x pour le débogage hérité

Le débogueur hérité ptvsd 3.x est la valeur par défaut dans Visual Studio 2017 version 15.7 et antérieure.

Selon votre configuration de Visual Studio, vous pourriez avoir besoin d’utiliser ptvsd 3.x pour le débogage à distance :

• Visual Studio 2017 version 15.7 et versions antérieures avec Python 2.6, 3.1 à 3.4, ou IronPython
• Visual Studio 2019 version 16.5 et versions ultérieures avec Python 2.6, 3.1 à 3.4, ou IronPython
• Premières versions 4.x

Si votre configuration implémente un scénario de version plus ancienne, Visual Studio affiche l’erreur, Le débogueur ne prend pas en charge cet environnement Python.

Configurer le débogage à distance

Pour vous préparer au débogage à distance avec ptvsd 3.x, suivez cette procédure :

1. Configurez votre secret, qui est utilisé pour limiter l’accès au script en cours d’exécution.

   Dans ptvsd 3.x, la fonction enable_attach nécessite que vous passiez un « secret » en tant que premier argument.

   • Lorsque vous attachez le débogueur distant, entrez le secret avec la commande enable_attach(secret="<secret>").

   Bien que vous puissiez autoriser tout le monde à se connecter en utilisant la commande enable_attach(secret=None), cette option n’est pas recommandée.

2. Créez votre URL de cible de connexion sous la forme tcp://<secret>@<ip_address>:5678.

   • tcp:// spécifie le type de connexion en tant que TCP.
   • <secret> est la chaîne passée avec la fonction enable_attach dans le code Python.
   • <ip_address> est l’adresse IP de l’ordinateur distant, qui peut être une adresse explicite ou un nom comme monvm.cloudapp.net.
   • :5678 est le numéro de port de débogage à distance.

Connexion sécurisée avec le protocole TCPS

Par défaut, la connexion au serveur de débogage à distance ptvsd 3.x est sécurisée uniquement par le secret, et toutes les données sont transmises en texte clair. Pour une connexion plus sécurisée, ptvsd 3.x prend en charge SSL en utilisant la forme sécurisée du protocole TCP, ou TCPS.

Utilisez les étapes suivantes pour configurer ptvsd 3.x afin de fonctionner avec le protocole TCPS :

1. Sur l’ordinateur distant, utilisez la commande openssl pour générer des fichiers distincts pour la clé et le certificat auto-signé :

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

   • À l’invite openssl, saisissez le nom d’hôte ou l’adresse IP que vous utilisez pour vous connecter pour le Nom commun.

   Pour plus d’informations, veuillez consulter la rubrique Certificats auto-signés dans la documentation du module ssl Python. Notez que la commande décrite dans la documentation Python génère uniquement un seul fichier combiné.

2. Dans le code, modifiez l’appel à la fonction enable_attach pour inclure les arguments certfile et keyfile en utilisant les noms de fichier comme valeurs. Ces arguments ont la même signification que pour la fonction Python standard ssl.wrap_socket.

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

   Vous pouvez également apporter la même modification dans le fichier de code sur l’ordinateur local. Comme ce code n’est pas réellement exécuté, il n’est pas strictement nécessaire.

3. Redémarrez le programme Python sur l’ordinateur distant pour qu’il soit prêt pour le débogage.

4. Sécurisez le canal en ajoutant le certificat à la racine de confiance sur l’ordinateur Windows avec Visual Studio :

   1. Copiez le fichier de certificat de l’ordinateur distant sur l’ordinateur local.

   2. Ouvrez le Panneau de configuration et rendez-vous dans Outils Windows>Gérer les certificats de l’ordinateur.

   3. Dans la boîte de dialogue certlm [Certificats - ordinateur local], développez le nœud Autorités de certification racines de confiance, faites un clic droit sur Certificats, et sélectionnez Toutes les tâches>Importer.

   4. Parcourez et sélectionnez le fichier .cer copié depuis l’ordinateur distant.

   5. Poursuivez à travers les invites de la boîte de dialogue pour terminer le processus d’importation.

5. Répétez le processus d’attachement dans Visual Studio, comme décrit précédemment dans Attacher à distance depuis Python Tools.

   Pour cette instance, définissez tcps:// comme le protocole pour la Cible de connexion (ou Qualificateur).

   

Résoudre les problèmes de connexion

Lors de la tentative de connexion, Visual Studio peut rencontrer des problèmes. Examinez les scénarios suivants et prenez les mesures appropriées, si nécessaire.

• Visual Studio vous avertit en cas d’éventuels problèmes de certificat lors de la connexion SSL.

  Action : vous pouvez ignorer le message et continuer.

  Attention

  Gardez à l’esprit que bien que le canal soit toujours crypté contre l’espionnage, il peut être ouvert aux attaques de l’homme du milieu.

• Visual Studio affiche l’avertissement certificat distant n’est pas approuvé .

  Problème : le certificat n’est pas correctement ajouté à l’autorité de certification racine approuvée.

  Action : Revérifiez les étapes permettant d’ajouter le certificat à l’autorité de certification racine approuvée sur l’ordinateur Windows, puis réessayez d’établir la connexion.

  

• Visual Studio affiche l’avertissement le nom de certificat distant ne correspond pas au nom de l’hôte.

  Problème : le nom correct d’hôte ou l’adresse IP n’est pas spécifié pour le nom commun pour le certificat.

  Action : Revérifiez les étapes de sécurisation de la connexion avec TCPS. Veillez à utiliser le nom commun correct lorsque vous créez le certificat, puis réessayez d’établir la connexion.

  

Contenu connexe

• Débogage à distance