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

Dans cet article, vous allez découvrir 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 autre système d’exploitation, appareil ou implémentation Python autre que CPython à l’aide de la bibliothèque de débogage .

Visual Studio 2019 version 16.4 et antérieure utilise la bibliothèque ptvsd . Dans Visual Studio 2019 version 16.5 et ultérieure, 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 de réseau ou de pare-feu sur l’ordinateur distant pour autoriser les connexions TCP.

Conditions préalables

• Visual Studio installé avec prise en charge des charges de travail Python. Pour plus d’informations, consultez Installer la prise en charge de Python dans Visual Studio.

• Un ordinateur distant exécutant Python sur un système d’exploitation tel que macOS ou Linux.

• Le port 5678 (entrant) s’ouvre sur le pare-feu de l’ordinateur distant, 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 à l’aide du Bureau à distance à partir de Windows. Ubuntu pour la machine virtuelle est pratique, car Python est installé par défaut. Si vous avez une autre configuration, consultez 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 plus d’informations sur la création d’une règle de pare-feu pour une machine virtuelle Azure, consultez les articles suivants :

• Filtrer le trafic réseau avec un groupe de sécurité réseau à l’aide du portail Azure
• Acheminer le trafic réseau avec une table de routage à l’aide du portail Azure
• déployer et configurer le 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 le débogage de 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 à l’aide de la commande pip3 install debugpy.

   Note

   Il est judicieux d’enregistrer la version de debugpy installée au cas où vous en auriez besoin pour la résolution des problèmes. Le référencement des debugpy affiche également les versions disponibles.

3. Activez le débogage à distance en ajoutant le code suivant en haut du fichier guessing-game.py avant d’autres codes. (Bien qu’il ne s’agit pas d’une exigence stricte, il est impossible de déboguer les threads d’arrière-plan générés avant l’appel de la fonction listen.)

   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 lorsque vous interagissez avec le programme. Si vous le souhaitez, 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 attache.

Conseil

Outre les fonctions listen et wait_for_client, debugpy fournit également une fonction d’assistance breakpoint. Cette fonction sert de point d’arrêt programmatique si le débogueur est attaché. Une autre fonction, is_client_connected1, retourne True si le débogueur est attaché. Vous n’avez pas besoin de vérifier ce résultat avant d’appeler d’autres fonctions debugpy.

Attacher à distance à partir des outils Python

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. Il n’importe pas où se trouve le fichier, mais son nom doit correspondre au nom du script sur l’ordinateur distant.

2. (Facultatif) Pour qu'IntelliSense pour debugpy fonctionne sur votre 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 Attacher au processus, définissez Type de connexion sur Python distant (debugpy).

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

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

6. Sélectionnez Entrez pour remplir la liste des processus de débogage disponibles sur cet ordinateur :

   

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

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

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

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

   

9. Lorsque vous arrêtez le débogage, Visual Studio se détache du programme. Le programme continue à 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

Passez en revue les points suivants pour résoudre les problèmes liés à la connexion.

• Veillez à sélectionner Python distant (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 de la cible de connexion correspond à celle de l’ordinateur distant.

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

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

• Vérifiez que la version debugpy installée sur l’ordinateur distant (tel que retourné par la commande pip3 list) correspond à la version de Visual 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

Note

Visual Studio 2019 version 16.0-16.4 utilisait ptvsd, pas debugpy. Le processus de cette procédure pas à pas pour ces versions est similaire, mais les noms de fonctions sont différents. Visual Studio 2019 version 16.5 utilise debugpy, mais les noms de fonction étaient identiques à ceux de 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.

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

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

Selon votre configuration de Visual Studio, vous devrez peut-être utiliser ptvsd 3.x pour le débogage à distance :

• Visual Studio 2017 version 15.7 et antérieure avec Python 2.6, 3.1 à 3.4 ou IronPython
• Visual Studio 2019 version 16.5 et ultérieure avec Python 2.6, 3.1 à 3.4 ou IronPython
• Versions antérieures de 4.x

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

Configurer le débogage à distance

Pour préparer le débogage à distance avec ptvsd 3.x, procédez comme suit :

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

   Dans ptvsd 3.x, la fonction enable_attach vous oblige à passer un « secret » comme premier argument.

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

   Bien que vous puissiez autoriser toute personne à se connecter à l’aide de la commande enable_attach(secret=None), cette option n’est pas recommandée.

2. Créez votre URL 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 myvm.cloudapp.net.
   • :5678 est le numéro de port de débogage distant.

Connexion sécurisée avec le protocole TCPS

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

Procédez comme suit pour configurer ptvsd 3.x pour qu’il fonctionne 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 de openssl, entrez le nom d’hôte ou l’adresse IP que vous utilisez pour vous connecter au nom commun .

   Pour plus d’informations, consultez certificats auto-signés dans la documentation du module Python ssl. Notez que la commande décrite dans la documentation Python ne génère qu’un seul fichier combiné.

2. Dans le code, modifiez l’appel à la fonction enable_attach pour inclure certfile et keyfile arguments à l’aide des noms de fichiers 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. Étant donné que 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 afin qu’il soit prêt pour le débogage.

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

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

   2. Ouvrez Panneau de configuration et accédez à Outils Windows>Gérer les certificats d’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, puis sélectionnez Toutes les tâches>Importer.

   4. Accédez au fichier .cer copié à partir de l’ordinateur distant et sélectionnez-le.

   5. Continuez à travers les fenêtres 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 à partir des outils Python.

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

   

Résoudre les problèmes de connexion

Pendant la tentative de connexion, Visual Studio peut rencontrer des problèmes. Passez en revue les scénarios suivants et effectuez l’action appropriée, si nécessaire.

• Visual Studio avertit les problèmes de certificat potentiels lors de la connexion via SSL.

  Action: vous pouvez ignorer le message et continuer.

  Attention

  Gardez à l’esprit que même si le canal est toujours chiffré contre l’écoute, il peut être ouvert aux attaques de l'homme du milieu.

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

  Problème : le certificat n'est pas ajouté correctement à l'Autorité de certification racine de confiance.

  Action : revérifiez les étapes pour ajouter le certificat à l’autorité de certification racine de confiance sur l’ordinateur Windows, et réessayez de vous connecter.

  

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

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

  Action: revérifiez les étapes décrites dans Sécuriser la connexion avec TCPS. Veillez à utiliser le nom commun correct lorsque vous créez le certificat, puis réessayez la connexion.

  

Contenu connexe

• Débogage à distance