Déboguez votre code Python dans Visual Studio
Visual Studio offre une expérience de débogage complète pour Python. Dans cet article, vous découvrirez comment attacher le débogueur à des processus en cours d’exécution et évaluer des expressions dans les fenêtres Espion et Exécution. Dans le débogueur, vous pouvez inspecter les variables locales, utiliser des points d’arrêt, pas à pas dans/sortir/au-dessus des instructions, Définir l’instruction suivante, etc.
Pour des informations de débogage spécifiques à un scénario, veuillez consulter les articles suivants :
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.
Code Python à utiliser avec le débogueur.
Déboguer du code avec ou sans projet
Si vous souhaitez contrôler votre environnement Python et les arguments, créez d’abord un projet pour votre code. Vous pouvez créer un projet avec le modèle de projet À partir de code Python existant. Pour plus d’informations, veuillez consulter l’article Créer un projet à partir de fichiers de code Python existants.
Cependant, vous n’avez pas besoin d’un fichier de projet ou de solution dans Visual Studio pour déboguer votre code Python. Pour déboguer du code dans un fichier Python autonome, ouvrez votre fichier dans Visual Studio et sélectionnez Déboguer>Démarrer le débogage. Visual Studio lance le script avec l’environnement global par défaut et sans arguments. Vous disposez alors d’un support complet de débogage pour votre code. Pour plus d'informations, voir Environnements Python.
Explorez le débogage de base
Le flux de travail de débogage de base implique de définir des points d’arrêt, de pas à pas dans le code, d’inspecter les valeurs et de gérer les exceptions. Vous pouvez démarrer une session de débogage en sélectionnant Déboguer>Démarrer le débogage ou en utilisant le raccourci clavier F5. Pour un projet, ces actions lancent le fichier de démarrage avec l’environnement actif du projet et les éventuels arguments de ligne de commande ou les chemins de recherche spécifiés pour Propriétés du projet. Pour configurer les propriétés, veuillez consulter la section Définir les options de débogage du projet.
Définir le fichier de démarrage du projet
Le fichier de démarrage d’un projet est indiqué en gras dans l’Explorateur de solutions. Vous pouvez choisir quel fichier utiliser comme fichier de démarrage.
- Pour spécifier un fichier de projet comme fichier de démarrage, faites un clic droit sur le fichier et sélectionnez Définir comme élément de démarrage.
Dans Visual Studio 2017 version 15.6 et les versions ultérieures, vous voyez une alerte si vous n’avez pas de fichier de démarrage spécifié. Les versions antérieures de Visual Studio peuvent ouvrir une fenêtre Sortie avec l’interpréteur Python en cours d’exécution, ou la fenêtre Sortie s’ouvre et se ferme brièvement.
Spécifier l’environnement actif
Si vous utilisez un fichier de projet, le débogueur démarre toujours avec l’environnement Python actif pour le projet. Vous pouvez changer l’environnement actif actuel. Pour plus d’informations, veuillez consulter la rubrique Sélectionner un environnement Python pour un projet.
Si vous déboguez un fichier de code Python autonome, Visual Studio lance le script avec l’environnement global par défaut et sans arguments.
Définir des points d’arrêt
Les points d’arrêt arrêtent l’exécution du code au niveau d’un point marqué, ce qui vous permet d’inspecter l’état du programme.
Certains points d’arrêt dans Python peuvent surprendre les développeurs habitués à d’autres langages de programmation. Dans Python, l’intégralité du fichier correspond à du code exécutable, de sorte que Python exécute le fichier lorsqu’il est chargé pour traiter n’importe quelle définition de fonction ou de classe de niveau supérieur. Si un point d’arrêt est défini, vous pourriez constater que le débogueur s’arrête en cours de déclaration de classe. Même s’il peut sembler surprenant, ce comportement est correct.
Pour définir un point d’arrêt, sélectionnez dans la marge de gauche de l’éditeur de code ou faites un clic droit sur une ligne de code et sélectionnez Point d’arrêt>Insérer un point d’arrêt. Un point rouge apparaît sur chaque ligne qui a un point d’arrêt défini.
Pour supprimer un point d’arrêt, sélectionnez le point rouge ou faites un clic droit sur la ligne de code et sélectionnez Point d’arrêt>Supprimer le point d’arrêt. Vous pouvez également désactiver un point d’arrêt en sélectionnant le point rouge et en sélectionnant Point d’arrêt>Désactiver le point d’arrêt.
Définir des conditions et des actions
Vous pouvez personnaliser les conditions de déclenchement d’un point d’arrêt, par exemple en demandant l’arrêt uniquement quand une variable est définie sur une certaine valeur ou plage de valeurs.
Pour définir des conditions, faites un clic droit sur le point rouge du point d’arrêt, sélectionnez Conditions. La boîte de dialogue Paramètres du point d’arrêt s’ouvre.
Dans la boîte de dialogue, vous pouvez ajouter plusieurs conditions et créer des expressions conditionnelles en utilisant du code Python. Pour plus d’informations sur cette fonctionnalité dans Visual Studio, consultez la section Conditions de point d’arrêt.
Vous avez également la possibilité de définir des Actions pour un point d’arrêt. Vous pouvez créer un message à enregistrer dans la fenêtre Sortie et éventuellement spécifier de continuer l’exécution automatiquement.
L’enregistrement d’un message crée un point de trace qui n’ajoute pas de code de journalisation à votre application directement.
Selon la façon dont vous configurez les conditions et les actions pour un point d’arrêt, l’icône rouge dans la marge de gauche change pour indiquer vos paramètres. Vous pouvez voir la forme du point, un chronomètre, ou un diamant.
Exécuter le code pas à pas
Lorsque Visual Studio arrête l’exécution du code à un point d’arrêt, plusieurs commandes peuvent être utilisées pour parcourir votre code ou exécuter des blocs de code avant de s’arrêter à nouveau. Les commandes sont disponibles à plusieurs endroits dans Visual Studio, notamment dans la barre d’outils Débogueur, le menu Déboguer, via un clic droit sur le menu contextuel dans l’éditeur de code et via des raccourcis clavier.
Le tableau suivant résume ces commandes et fournit le raccourci clavier :
| Commande | Raccourci | Description |
|---|---|---|
| Stop | Maj+F5 | Arrêtez la session de débogage. |
| Restart | Ctrl+Maj+F5 | Redémarrez la session de débogage en cours. |
| Continuer | F5 | Exécuter le code jusqu’à ce que vous atteigniez le prochain point d’arrêt. |
| Pas à pas détaillé | F11 | Exécuter la prochaine instruction et s’arrêter. Si la prochaine instruction est un appel à une fonction, le débogueur s’arrête à la première ligne de la fonction appelée. |
| Pas à pas principal | F10 | Exécuter la prochaine instruction, y compris faire un appel à une fonction (exécutant tout son code) et appliquer toute valeur de retour. Cette commande vous permet de passer facilement les fonctions que vous n’avez pas besoin de déboguer. |
| Pas à pas sortant | Maj+F11 | Exécuter le code jusqu’à la fin de la fonction actuelle, puis passer à l’instruction d’appel. Cette commande est utile quand vous n’avez pas besoin de déboguer le reste de la fonction actuelle. |
| Exécuter jusqu’au curseur | Ctrl+F10 | Exécuter le code jusqu’à l’emplacement du curseur dans l’éditeur. Cette commande vous permet d’ignorer facilement un segment de code que vous n’avez pas besoin de déboguer. |
| Définir l’instruction suivante | Ctrl+Maj+F10 | Changer le point d’exécution actuel dans le code à l’emplacement du curseur. Cette commande vous permet d’omettre totalement l’exécution d’un segment de code donné, par exemple quand vous savez que le code est défectueux ou qu’il produit un effet indésirable. |
| Afficher l’instruction suivante | Alt+Num+\ | Revenir à l’instruction suivante à exécuter dans le code. Cette commande vous aide à localiser l’endroit dans votre code où le débogueur est arrêté. |
Inspecter et modifier les valeurs
Lorsque vous arrêtez l’exécution du code dans le débogueur, vous pouvez inspecter et modifier les valeurs des variables. Vous pouvez également utiliser la fenêtre Espion pour effectuer un monitoring des variables individuelles et des expressions personnalisées. Pour plus d’informations, veuillez consulter la rubrique Inspecter les variables.
Pour afficher une valeur à l’aide de la fonctionnalité DataTips pendant le débogage, survolez la souris sur n’importe quelle variable dans l’éditeur. Vous pouvez sélectionner la valeur de la variable pour la modifier :
Pour utiliser la fenêtre Automatique, sélectionnez Déboguer>Fenêtres>Automatique. Cette fenêtre contient les variables et les expressions proches de l’instruction courante. Vous pouvez double-cliquer dans la colonne de valeur ou sélectionner et appuyer sur F2 pour modifier la valeur :
Pour plus d’informations sur l’utilisation de la fenêtre Automatique, veuillez consulter la rubrique Inspecter les variables dans les fenêtres Automatique et Variables locales.
Pour utiliser la fenêtre Variables locales, sélectionnez Déboguer>Fenêtres>Variables locales. Cette fenêtre affiche toutes les variables qui sont dans le contexte courant, qui peuvent également être modifiées :
Pour plus d’informations sur l’utilisation de la fenêtre Variables locales, veuillez consulter la rubrique Inspecter les variables dans les fenêtres Automatique et Variables locales.
Pour utiliser les fenêtres Espion, sélectionnez Déboguer>Fenêtres>Espion>Espion 1-4. Cette option vous permet d’entrer des expressions Python arbitraires et de voir les résultats. Les expressions sont réévaluées pour chaque étape :
Pour plus d’informations sur l’utilisation de la fenêtre Espion, veuillez consulter la rubrique Placer une surveillance sur des variables avec les fenêtres Espion et Espion Express.
Pour inspecter une valeur de chaîne, sélectionnez Afficher (la loupe) sur le côté droit de l’entrée Valeur. Les types
str,unicode,bytesetbytearraysont tous disponibles pour l’inspection.Le menu déroulant Afficher présente quatre options de visualisation : Texte, HTML, XML ou JSON.
Après avoir sélectionné une visualisation, une boîte de dialogue s’affiche montrant la valeur de la chaîne non entre guillemets selon le type sélectionné. Vous pouvez voir la chaîne avec enroulement et défilement, coloration syntaxique et vues arborescentes. Ces visualisations peuvent aider à déboguer les problèmes avec des chaînes longues et complexes.
Voir les exceptions
Si une erreur survient dans votre programme lors du débogage, mais que vous ne disposez pas d’un gestionnaire d’exceptions à cet effet, le débogueur s’arrête au niveau de l’exception :
Lorsqu’une erreur se produit, vous pouvez inspecter l’état actuel du programme, comme la pile d’appels. Cependant, si vous parcourez le code étape par étape, le processus de débogage continue de lancer l’exception jusqu’à ce qu’elle soit gérée ou que votre programme se termine.
Pour voir une vue élargie des exceptions, sélectionnez Déboguer>Fenêtres>Paramètres des exceptions.
Dans la fenêtre Paramètres des exceptions, la case à cocher à côté d’une exception contrôle si le débogueur interrompt toujours l’exécution lorsque cette exception est levée.
Pour interrompre plus souvent pour une exception particulière, sélectionnez la case à cocher à côté de l’exception dans la fenêtre Paramètres des exceptions.
Par défaut, la plupart des exceptions provoquent une interruption lorsque le gestionnaire d’exceptions ne peut pas être trouvé dans le code source. Pour modifier ce comportement, cliquez avec le bouton droit sur une exception et modifiez l’option Continuer en cas d’exception non gérée dans le code utilisateur. Pour interrompre moins souvent pour l’exception, désélectionnez cette option.
Pour configurer une exception qui n’apparaît pas dans la fenêtre Paramètres des exceptions, sélectionnez Ajouter (symbole plus). Entrez un nom pour l’exception à surveiller. Indiquez un nom correspondant au nom complet de l’exception.
Configurer les options de débogage du projet
Par défaut, le débogueur démarre votre programme avec le lanceur Python standard, sans aucun argument de ligne de commande et aucun autre chemin d’accès ni condition spéciaux. Vous pouvez configurer les options de démarrage pour un projet Python en définissant les propriétés de débogage.
Pour accéder aux propriétés de débogage d’un projet, cliquez avec le bouton droit sur votre projet Python dans Explorateur de solutions, sélectionnez Propriétés, puis sélectionnez l’onglet Débogage.
Les sections suivantes décrivent les propriétés spécifiques.
Définir le comportement de lancement
Le tableau suivant liste les valeurs possibles pour la propriété Mode de lancement. Utilisez cette propriété pour définir le comportement de lancement pour le débogueur.
| Valeur | Description |
|---|---|
| Standard Python launcher (Lanceur Python standard) | Utilisez du code de débogage écrit en Python portable compatible avec CPython, IronPython et des variantes comme Stackless Python. Cette option offre la meilleure expérience pour le débogage du code Python pur. Lorsque vous vous attachez à un processus python.exe en cours d’exécution, le lanceur spécifié dans cette propriété est utilisé. Ce lanceur permet également le débogage mixte pour CPython, ce qui vous permet de passer sans problème entre le code C/C++ et le code Python. |
| Lanceur web | Démarrez votre navigateur par défaut au lancement et activez le débogage des modèles. Pour plus d’informations, veuillez consulter la section Débogage de modèles Web. |
| Django Web launcher (Lanceur web Django) | Implémentez un comportement identique à la propriété Lanceur Web mais pour un environnement Django. Utilisez cette option uniquement à des fins de rétrocompatibilité. |
| Lanceur IronPython (.NET) | Utilisez le débogueur .NET, qui fonctionne uniquement avec IronPython mais permet de passer entre n’importe quel projet de langue .NET, y compris C# et Visual Basic. Ce launcher est utilisé si vous vous attachez à un processus .NET en cours d’exécution qui héberge IronPython. |
Définir le comportement d’exécution
Le tableau suivant décrit les propriétés que vous pouvez définir pour configurer le comportement d’exécution pour le débogueur.
| Propriété | Description |
|---|---|
| Chemins de recherche | Spécifiez les chemins de fichiers et de dossiers que Visual Studio utilise pour votre projet. Ces valeurs correspondent aux éléments affichés dans le nœud Chemins de recherche du projet dans Explorateur de solutions. Bien que vous puissiez spécifier des chemins de recherche dans cette boîte de dialogue, il peut être plus facile d’utiliser Explorateur de solutions, où vous pouvez parcourir les dossiers et convertir automatiquement les chemins en forme relative. |
| Arguments de script | Définissez les arguments à ajouter à la commande que Visual Studio utilise pour lancer votre script, et qui apparaissent après le nom de fichier de votre script. Le premier élément listé dans la valeur est disponible pour votre script en tant que sys.argv[1], le second en tant que sys.argv[2], etc. |
| Interpreter Arguments (Arguments d’interpréteur) | Listez les arguments à ajouter à la ligne de commande du Launcher avant le nom de votre script. Les arguments courants sont -W ... pour contrôler les avertissements, -O pour optimiser légèrement votre programme, et -u pour utiliser une IO non tamponnée. Les utilisateurs IronPython utilisent généralement ce champ pour transmettre des options -X, telles que -X:Frames ou -X:MTA. |
| Chemin d’interpréteur | Identifiez un chemin d’interpréteur pour remplacer le chemin associé à l’environnement actuel. La valeur peut être utile pour lancer votre script avec un interpréteur non standard. |
| Variables d’environnement | Utilisez cette propriété pour ajouter des entrées sous la forme <NAME>=\<VALUE>. Visual Studio applique cette valeur de propriété en dernier, par-dessus toutes les variables d’environnement globales existantes, et après que PYTHONPATH est défini selon le paramètre Chemins de recherche. Par conséquent, ce paramètre peut être utilisé pour remplacer manuellement n’importe laquelle de ces autres variables. |
Travailler avec des fenêtres interactives
Il existe deux fenêtres interactives que vous pouvez utiliser pendant une session de débogage : la fenêtre Exécution standard de Visual Studio et la fenêtre Python Debug Interactive.
Ouvrir la fenêtre Exécution
Vous pouvez utiliser la fenêtre Exécution standard de Visual Studio pour évaluer rapidement des expressions Python et inspecter ou assigner des variables dans votre programme en cours d’exécution. Pour plus d’informations, consultez Fenêtre Exécution.
- Pour ouvrir la fenêtre Exécution, sélectionnez Déboguer>Fenêtres>Exécution. Vous pouvez également utiliser le raccourci clavier Ctrl+Alt+I.
Ouvrir la fenêtre Debug Interactive
La fenêtre Python Debug Interactive offre un environnement riche avec l’expérience complète de REPL interactif disponible pendant le débogage, y compris l’écriture et l’exécution de code. Cette fenêtre se connecte automatiquement à tout processus démarré dans le débogueur en utilisant le lanceur Python Standard, y compris les processus attachés via Déboguer>Attacher au Processus. Cependant, cette fenêtre n’est pas disponible lors de l’utilisation du débogage mixte C/C++.
Pour utiliser la fenêtre Debug Interactive, sélectionnez Déboguer>Fenêtres>Python Debug Interactive (Shift+Alt+I).
La fenêtre Debug Interactive prend en charge des méta-commandes spéciales en plus des commandes REPL standards, comme décrit dans le tableau suivant :
| Commande | Description |
|---|---|
$continue, $cont, $c |
Commencer à exécuter le programme à partir de l’instruction actuelle. |
$down, $d |
Abaisse le frame actuel d’un niveau dans la trace de la pile. |
$frame |
Afficher l’ID du cadre courant. |
$frame |
Changer le cadre courant pour l’ID de cadre spécifié. - Nécessite un argument <ID de cadre>. |
$load |
Charger les commandes depuis un fichier et les exécuter jusqu’à la fin. |
$proc |
Afficher l’ID du processus courant. |
$proc |
Changer le processus courant pour l’ID de processus spécifié. - Nécessite un argument <ID de processus>. |
$procs |
Lister les processus actuellement en cours de débogage. |
$stepin, $step, $s |
Entrer dans l’appel de fonction suivant, si possible. |
$stepout, $return, $r |
Sortir de la fonction courante. |
$stepover, $until, $unt |
Passer par-dessus l’appel de fonction suivant. |
$thread |
Afficher l’ID du thread courant. |
$thread |
Changer le thread courant pour l’ID de fil spécifié. - Nécessite un argument <ID de thread>. |
$threads |
Lister les threads actuellement en cours de débogage. |
$up, $u |
Remonte le frame actuel d’un niveau dans l’arborescence des appels de procédure. |
$where, $w, $bt |
Lister les cadres pour le thread courant. |
Les fenêtres du débogueur standard telles que Processus, Threads et Pile des appels ne sont pas synchronisées avec la Fenêtre interactive de débogage. Si vous changez le processus, le thread, ou le cadre actif dans la fenêtre Debug Interactive, les autres fenêtres de débogueur ne sont pas affectées. De même, le fait de changer le processus, le thread ou le frame actif dans les autres fenêtres du débogueur n’affecte pas la Fenêtre interactive de débogage.
Utiliser le débogueur hérité
Selon la configuration de votre environnement, vous pourriez avoir besoin d’utiliser le débogueur d’ancienne génération :
- 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
- versions ptvsd 3.x et début 4.x
Le débogueur d’ancienne génération est par défaut dans Visual Studio 2017 version 15.7 et versions antérieures.
- Pour utiliser le débogueur d’ancienne génération, sélectionnez Outils>Options, développez les options de Python>Débogage et sélectionnez l’option Utiliser le débogueur d’ancienne génération.
Prise en charge les anciennes versions de Visual Studio ou Python
Visual Studio 2017 version 15.8 et ultérieures utilisent un débogueur basé sur la version 4.1 de ptvsd et suivantes. Visual Studio 2019 version 16.5 et ultérieures utilisent un débogueur basé sur debugpy. Ces deux versions du débogueur sont compatibles avec Python 2.7 ou Python 3.5 et versions ultérieures.
Si vous utilisez l’une de ces versions de Visual Studio, mais que vous utilisez Python 2.6, 3.1 à 3.4, ou IronPython, Visual Studio affiche l’erreur, Le débogueur ne prend pas en charge cet environnement Python :
Lorsque Visual Studio signale cette erreur d’environnement, vous devez utiliser le débogueur d’ancienne génération.
Prise en charge les anciennes versions de ptvsd
Si vous utilisez une ancienne version de ptvsd dans l’environnement actuel (comme une version antérieure à 4.0.x, ou une version 3.x requise pour le débogage à distance), Visual Studio pourrait afficher une erreur ou un avertissement.
Si votre environnement utilise ptvsd 3.x, Visual Studio affiche l’erreur, Le paquet de débogage n’a pas pu être chargé :
L’avertissement, Le paquet de débogage est obsolète, apparaît lorsque vous utilisez une version antérieure de ptvsd 4.x :
Lorsque Visual Studio signale ces erreurs d’environnement, vous devez utiliser le débogueur d’ancienne génération.
Important
Bien que vous puissiez choisir d’ignorer l’avertissement pour certaines versions de ptvsd, Visual Studio pourrait ne pas fonctionner correctement.
Gérer votre installation de ptvsd
Suivez cette procédure pas à pas pour gérer votre installation de ptvsd :
Dans la fenêtre Environnements Python, rendez-vous sur l’onglet Paquets.
Saisissez ptvsd dans le champ de recherche et examinez la version installée de ptvsd :
Si la version est inférieure à 4.1.1a9 (la version groupée avec Visual Studio), sélectionnez le X à droite du package pour désinstaller l’ancienne version. Visual Studio utilise alors sa version groupée. (Vous pouvez également désinstaller depuis PowerShell en utilisant la commande
pip uninstall ptvsd.)Alternativement, vous pouvez mettre à jour le paquet ptvsd vers sa dernière version en suivant les instructions se trouvant dans la section Dépanner les scénarios de débogage.
Résolution des problèmes relatifs aux scénarios de débogage
Les scénarios suivants décrivent d’autres options de dépannage pour votre configuration de débogage.
Mettre à niveau ptvsd pour Visual Studio 2019
Si vous rencontrez des problèmes avec le débogueur dans Visual Studio 2019 version 16.4 et versions antérieures, mettez d’abord à niveau votre version du débogueur comme suit :
Dans la fenêtre Environnements Python, rendez-vous sur l’onglet Paquets.
Saisissez ptvsd --upgrade dans le champ de recherche, puis sélectionnez Exécuter la commande : pip install ptvsd --upgrade. (Vous pouvez également utiliser la même commande à partir de PowerShell.)
Si les problèmes persistent, créez un ticket sur le Référentiel GitHub de PTVS.
Remarque
Pour Visual Studio 2019 16.5 et les versions ultérieures, le débogage fait partie de la charge de travail Python de Visual Studio, et est mis à jour en même temps que Visual Studio.
Activer la journalisation du débogueur
Dans le cadre de l’investigation d’un problème de débogueur, Microsoft pourrait vous demander d’activer et de collecter les journaux du débogueur pour aider au diagnostic.
Les étapes suivantes permettent le débogage dans la session active de Visual Studio :
Ouvrez une fenêtre de commande dans Visual Studio en sélectionnant Affichage>Autres Fenêtres>Fenêtre de Commande.
Entrez la commande suivante :
DebugAdapterHost.Logging /On /OutputWindowCommencez le débogage et suivez les étapes nécessaires pour reproduire votre problème. Pendant ce temps, les journaux de débogage s’affichent dans la Fenêtre Sortie sous Journaux de l’hôte d’adaptateur de débogage. Vous pouvez ensuite copier les journaux de cette fenêtre et les coller dans un problème GitHub, un email, etc.
Si Visual Studio cesse de répondre ou si vous ne pouvez pas accéder à la fenêtre Sortie, redémarrez Visual Studio, ouvrez une fenêtre Commande, puis entrez la commande suivante :
DebugAdapterHost.Logging /OnCommencez le débogage et reproduisez votre problème. Les journaux du débogueur se trouvent dans
%temp%\DebugAdapterHostLog.txt.
