Déboguer votre code Python

S’applique à : Visual Studio Visual Studio pour Mac Visual Studio Code

Visual Studio offre une expérience de débogage complète pour Python, notamment l’attachement à des processus en cours d’exécution, l’évaluation des expressions dans les fenêtres Espion et Exécution , l’inspection des variables locales, des points d’arrêt, des instructions pas à pas/out/over, l’instruction Set Next, etc.

Consultez également les articles ci-après concernant le débogage propre à un scénario :

• Débogage à distance Linux
• Débogage Python/C++ en mode mixte
• Symboles de débogage en mode mixte

Conseil

Python dans Visual Studio prend en charge le débogage sans projet. Après avoir ouvert un fichier Python autonome, cliquez avec le bouton droit dans l’éditeur, puis sélectionnez Démarrer avec débogage. Visual Studio lance alors le script avec l’environnement global par défaut (voir Environnements Python) sans aucun argument. Mais vous bénéficiez désormais d’une prise en charge complète du débogage.

Pour contrôler l’environnement et les arguments, créez un projet pour le code. Vous pouvez facilement effectuer cette opération à l’aide du modèle de projet À partir de code Python existant.

Bases du débogage

Le flux de travail de débogage de base implique la définition de points d’arrêt, l’exécution de code pas à pas, l’inspection de valeurs et la gestion des exceptions, comme décrit dans les sections suivantes.

Une session de débogage commence par la commande Démarrer> ledébogage, le bouton Démarrer dans la barre d’outils ou la touche F5. Ces opérations lancent le fichier de démarrage de votre projet (indiqué en gras dans l’Explorateur de solutions) avec l’environnement actif du projet et tous les arguments de ligne de commande ou chemins de recherche qui ont été spécifiés dans Propriétés du projet (consultez la section Options de débogage d’un projet). Visual Studio 2017 version 15.6 et ultérieures vous avertit si vous n’avez pas de fichier de démarrage défini ; les versions antérieures peuvent ouvrir une fenêtre de sortie avec l’interpréteur Python en cours d’exécution, ou la fenêtre de sortie s’affiche brièvement et disparaît. Dans tous les cas, cliquez avec le bouton droit sur le fichier approprié et sélectionnez Définir comme fichier de démarrage.

Notes

Le débogueur démarre toujours avec l’environnement Python actif associé au projet. Pour changer d’environnement, activez-en un autre en suivant les instructions de la page Sélectionner un environnement Python pour un projet.

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. Définissez des points d’arrêt en cliquant dans la marge gauche de l’éditeur de code ou en cliquant avec le bouton droit sur une ligne de code et en sélectionnantPoint d’arrêt Insérer un point> d’arrêt. Un point rouge apparaît sur chaque ligne comportant un point d’arrêt.

Cliquer sur le point rouge ou cliquer avec le bouton droit sur la ligne de code et sélectionner Le point> d’arrêtSupprimer le point d’arrêt supprime le point d’arrêt. Vous pouvez également le désactiver sans le supprimer à l’aide de la commande Désactiver le point>d’arrêt .

Notes

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 a été défini, il est possible que le débogueur marque un arrêt à mi-chemin d’une déclaration de classe. Même s’il peut sembler surprenant, ce comportement est correct.

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, cliquez avec le bouton droit sur le point rouge du point d’arrêt, sélectionnez Condition, puis créez des expressions à l’aide d’un code Python. Pour plus d’informations sur cette fonctionnalité dans Visual Studio, consultez la section Conditions de point d’arrêt.

Lorsque vous définissez des conditions, vous pouvez également définir Action et créer un message à consigner dans la fenêtre de sortie, tout en demandant éventuellement la poursuite automatique de l’exécution. La journalisation d’un message crée un point de trace sans l’ajout d’un code de journalisation directement dans votre application :

Exécuter le code pas à pas

Une fois arrêté au niveau d’un point d’arrêt, vous disposez de différentes méthodes pour exécuter le code pas à pas ou pour exécuter des blocs de code avant de marquer un nouvel arrêt. Ces commandes sont disponibles à divers emplacements, notamment la barre d’outils de débogage supérieure, le menu Débogage, le menu contextuel dans l’éditeur de code et certains raccourcis clavier (même si certaines de ces commandes ne sont pas disponibles à tous ces emplacements) :

Fonctionnalité	Séquence de touches	Description
Continuer	F5	Exécute le code jusqu’au point d’arrêt suivant.
Pas à pas détaillé	F11	Exécute l’instruction suivante et s’arrête. Si l’instruction suivante correspond à l’appel d’une fonction, le débogueur s’arrête à la première ligne de la fonction appelée.
Pas à pas principal	F10	Exécute l’instruction suivante, y compris l’appel d’une fonction (en exécutant la totalité de son code) et l’application de toute valeur renvoyée. Le mode pas à pas principal vous permet d’ignorer facilement les fonctions que vous n’avez pas besoin de déboguer.
Pas à pas sortant	Période de travail+F11	Exécute le code jusqu’à la fin de la fonction actuelle, puis procède à une exécution pas à pas jusqu’à l’instruction appelante. 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écute le code jusqu’à l’emplacement du signe insertion 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+Période de travail+F10	Remplace le point d’exécution actuel dans le code par l’emplacement du point d’insertion. 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*	Vous renvoie à la prochaine instruction à exécuter. Cette commande est utile si vous avez parcouru votre code et que vous ne vous souvenez pas de l’endroit où le débogueur s’est arrêté.

Inspecter et modifier les valeurs

Lorsque vous êtes arrêté dans le débogueur, vous pouvez inspecter et modifier les valeurs des variables. Vous pouvez également utiliser la fenêtre Espion pour surveiller des variables individuelles et des expressions personnalisées. (Pour obtenir des informations générales, consultez la section Inspect Variables (Inspecter des variables).)

Pour visualiser une valeur à l’aide des DataTips, il vous suffit de positionner le pointeur de la souris sur une variable quelconque dans l’éditeur. Vous pouvez sélectionner la valeur pour la modifier :

La fenêtre Automatique (Débogage>Fenêtres>Automatique) contient les variables et expressions qui sont proches de l’instruction actuelle. Vous pouvez double-cliquer sur la colonne Valeur ou sélectionner une valeur et appuyer sur F2 pour la modifier :

La fenêtre Variables locales (Débogage>Fenêtres>Variables locales) affiche toutes les variables qui se trouvent dans la portée actuelle et que vous pouvez modifier :

Pour plus d’informations sur l’utilisation des fenêtres Automatique et Variables locales, consultez l’article Inspecter les variables dans les fenêtres Automatique et Variables locales.

Les Fenêtres Espion (Débogage>Fenêtres>Espion>Espion 1-4) vous permettent d’entrer des expressions Python arbitraires et d’en visualiser les résultats. Les expressions sont réévaluées pour chaque étape :

Pour plus d’informations sur l’utilisation de la fonctionnalité Espion, consultez l’article Définir un espion sur les variables à l’aide des Fenêtres Espion et Espion express.

Pendant l’inspection d’une valeur de chaîne (str, unicode, bytes et bytearray sont toutes considérées comme des chaînes dans ce but), une icône Loupe apparaît à droite de la valeur. La sélection de l’icône affiche la valeur de chaîne non mise en guillemet dans une boîte de dialogue contextuelle, avec habillage et défilement, ce qui est utile pour les chaînes longues. En outre, la sélection de la flèche déroulante vers le bas en regard de l’icône vous permet de sélectionner des visualisations aux formats texte brut, HTML, XML et JSON :

Les visualisations HTML, XML et JSON apparaissent dans des fenêtres contextuelles distinctes avec des arborescences et mise en surbrillance de la syntaxe.

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 :

À ce stade, vous pouvez inspecter l’état du programme, y compris la pile des appels. Toutefois, si vous tentez de parcourir le code, l’exception continue d’être levée jusqu’à ce qu’elle soit gérée ou que votre programme se ferme.

La commande Debug>Windows>Exception Settings affiche une fenêtre dans laquelle vous pouvez développer des exceptions Python :

La case à cocher pour chaque exception détermine si le débogueur se interrompt toujours lorsqu’il est déclenché. Cochez cette case si vous souhaitez que le débogueur s’arrête plus souvent pour une exception spécifique.

Par défaut, le débogueur s’arrête pour la plupart des exceptions quand aucun gestionnaire d’exceptions ne figure 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. Si vous préférez que le débogueur s’arrête moins souvent pour une exception donnée, décochez cette case.

Pour configurer une exception qui n’apparaît pas dans cette liste, sélectionnez le bouton Ajouter pour l’ajouter. Indiquez un nom correspondant au nom complet de l’exception.

Options de débogage d’un 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. Les options de démarrage sont modifiées via les propriétés de débogage du projet accessibles en cliquant avec le bouton droit sur votre projet dans l’Explorateur de solutions, en sélectionnant Propriétés et en sélectionnant l’onglet Débogage .

Options du mode de lancement

Option	Description
Standard Python launcher (Lanceur Python standard)	Utilise le code de débogage écrit en Python portable qui est compatible avec CPython, IronPython et des variantes telles que Python Stackless. Cette option offre la meilleure expérience en matière de débogage de code Python pure. Quand vous effectuez un attachement à un processus python.exe en cours d’exécution, ce lanceur est utilisé. Ce lanceur fournit également un débogage en mode mixte pour CPython, ce qui vous permet d’exécuter un pas à pas détaillé alternant en toute transparence entre du code C/C++ et du code Python.
Lanceur web	Démarre votre navigateur par défaut au lancement et active le débogage des modèles. Pour plus d’informations, consultez la section consacrée au débogage de modèles web.
Django Web launcher (Lanceur web Django)	Identique au lanceur web et uniquement affiché pour des raisons de compatibilité descendante.
Lanceur IronPython (.NET)	Utilise le débogueur .NET, qui fonctionne uniquement avec IronPython, mais autorise l’exécution d’un pas à pas détaillé sur n’importe quel projet en langage .NET, y compris C# et VB. Ce lanceur est utilisé si vous effectuez un attachement à un processus .NET en cours d’exécution hébergeant IronPython.

Options d’exécution (chemins de recherche, arguments de démarrage et variables d’environnement)

Option	Description
Chemins de recherche	Ces valeurs correspondent à ce qui s’affiche dans le nœud Chemins de recherche du projet dans l’Explorateur de solutions. Vous pouvez modifier cette valeur à cet emplacement, mais il est plus facile d’utiliser l’Explorateur de solutions qui vous permet de parcourir les dossiers et convertit automatiquement les chemins sous leur forme relative.
Arguments de script	Ces arguments sont ajoutés à la commande utilisée pour lancer votre script, apparaissant après le nom de fichier du script. Le premier argument spécifié à cet emplacement est disponible pour votre script sous la forme sys.argv[1], le deuxième argument apparaît sous la forme sys.argv[2], etc.
Interpreter Arguments (Arguments d’interpréteur)	Ces arguments sont ajoutés à la ligne de commande du lanceur avant le nom de votre script. Les arguments couramment indiqués à cet emplacement sont -W ... pour contrôler les avertissements, -O pour optimiser légèrement votre programme et -u pour utiliser des E/S non mises en mémoire tampon. Les utilisateurs IronPython utilisent généralement ce champ pour transmettre des options -X, telles que -X:Frames ou -X:MTA.
Chemin d’accès de l’interprét	Remplace le chemin d’accès associé à l’environnement actuel. La valeur peut être utile pour lancer votre script avec un interpréteur non standard.
Variables d’environnement	Dans cette zone de texte multiligne, ajoutez des entrées du formulaire <NAME>=<VALUE>. Étant donné que ce paramètre est appliqué en dernier, au-dessus de toutes les variables d’environnement globales existantes, et une fois PYTHONPATH défini en fonction du paramètre Chemins de recherche , il peut être utilisé pour remplacer manuellement l’une de ces autres variables.

Fenêtres Exécution et Interactive

Dans le cadre d’une session de débogage, vous pouvez utiliser deux fenêtres interactives : la fenêtre Exécution Visual Studio standard et la fenêtre interactive de débogage Python.

La fenêtre Exécution (Débogage>Fenêtres>Exécution) est utilisée pour une évaluation rapide des expressions Python et pour l’inspection ou l’affectation de variables au sein du programme en cours d’exécution. Pour plus d’informations, consultez l’article général Fenêtre Exécution.

La fenêtre interactive de débogage Python (Débogage>Fenêtres>Fenêtre interactive de débogage Python) est plus élaborée, car elle offre une expérience REPL interactive complète au cours du débogage, notamment pour l’écriture et l’exécution de code. Il se connecte automatiquement à n’importe quel processus démarré dans le débogueur à l’aide du lanceur Python Standard (y compris les processus attachés par le biais de l’attachement au débogage>au processus). Toutefois, cette fenêtre n’est pas disponible en cas d’utilisation du débogage C/C++ en mode mixte.

Outre les commandes REPL standard, la fenêtre de débogage interactive prend en charge des méta commandes spéciales :

Commande	Arguments	Description
$continue, $cont, $c	Démarre l’exécution du programme à partir de l’instruction actuelle.
$down, $d	Abaisse le frame actuel d’un niveau dans la trace de la pile.
$frame		Affiche l’ID du frame actuel.
$frame	frame id	Remplace le frame actuel par l’ID de frame spécifié.
$load	Charge les commandes d’un fichier et s’exécute jusqu’à la fin.
$proc		Affiche l’ID du processus actuel.
$proc	process id	Remplace le processus actuel par l’ID de processus spécifié.
$procs		Répertorie les processus en cours de débogage.
$stepin, $step, $s	Effectue un pas à pas détaillé dans l'appel de fonction suivant, si possible.
$stepout, $return, $r	Sort de la fonction active.
$stepover, $until, $unt	Passe à l'appel de fonction suivant.
$thread		Affiche l’ID du thread actuel.
$thread	thread ID	Remplace le thread actuel par l’ID de thread spécifié.
$threads		Répertorie les threads en cours de débogage.
$up, $u		Déplacez le cadre actuel d’un niveau dans la trace de pile.
$where, $w, $bt	Répertorie les frames du thread actuel.

Les fenêtres de débogueur standard telles que les processus, les threads et la pile des appels ne sont pas synchronisées avec la fenêtre Interactive de débogage . La modification du processus actif, du thread ou du frame dans la fenêtre interactive de débogage n’affecte pas les autres fenêtres du débogueur. De même, la modification du processus actif, du thread ou du cadre dans les autres fenêtres du débogueur n’affecte pas la fenêtre Interactive de débogage .

Utiliser le débogueur hérité

Visual Studio 2017 version 15.8 et les versions ultérieures utilisent un débogueur basé sur ptvsd version 4.1+. Visual Studio 2019 versions 16.5 et ultérieures utilisent un débogueur basé sur le débogage. Ces versions du débogueur sont compatibles avec Python 2.7 et Python 3.5+. Si 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 :

Dans ces cas, vous devez utiliser l’ancien débogueur (qui est la valeur par défaut dans Visual Studio 2017 versions 15.7 et antérieures). Sélectionnez la commandeoptionsdes outils>, accédez audébogagePython>, puis sélectionnez l’option Utiliser le débogueur hérité.

Si vous avez installé une ancienne version de ptvsd dans l’environnement actuel (par exemple une ancienne version 4.0.x ou une version 3.x nécessaire au débogage à distance), Visual Studio peut afficher une erreur ou un avertissement.

L’erreur Impossible de charger le package du débogueur s’affiche quand vous avez installé ptvsd 3.x :

Dans ce cas, sélectionnez Utiliser le débogueur hérité pour définir l’option Utiliser le débogueur hérité, puis redémarrez le débogueur.

L’avertissement Le package du débogueur est obsolète s’affiche quand vous avez installé une ancienne version 4.x de ptvsd :

Important

Bien que vous puissiez choisir d’ignorer l’avertissement pour certaines versions de ptvsd, Visual Studio peut ne pas fonctionner correctement.

Pour gérer votre installation de ptvsd :

1. Accédez à l’onglet Packages de la fenêtre Environnements Python.

2. Entrez « ptvsd » dans le champ de recherche, puis examinez la version installée de ptvsd :

   

3. 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 la désinstaller à l’aide de PowerShell via pip uninstall ptvsd.)

4. Autre possibilité : vous pouvez mettre à jour le package ptvsd (dernière version) en suivant les instructions de la section Résolution des problèmes.

Dépannage

Pour Visual Studio 2019 (version 16.4 et antérieure) mise à niveau ptvsd

Si vous rencontrez des problèmes avec le débogueur, commencez par mettre à niveau votre version du débogueur comme suit :

1. Accédez à l’onglet Packages de la fenêtre Environnements Python.

2. Entrez ptvsd --upgrade dans la zone 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, signalez-les dans le référentiel GitHub PTVS.

   Notes

   Pour Visual Studio 2019 version 16.5 et ultérieure, le débogage fait partie de la charge de travail Python de Visual Studio et est mis à jour avec Visual Studio.

Activer la journalisation du débogueur

Au cours d’une enquête sur un problème de débogueur, Microsoft est susceptible de vous demander d’activer et de recueillir les journaux de débogage, qui facilitent le diagnostic.

Les étapes suivantes permettent le débogage dans la session active de Visual Studio :

1. Ouvrez une fenêtre de commande dans Visual Studio à l’aide de la commande Afficher>d’autresfenêtres de commande Windows>.

2. Entrez la commande suivante :

   DebugAdapterHost.Logging /On /OutputWindow
   

3. Commencez le débogage et suivez toutes 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 alors copier les journaux de cette fenêtre et les coller dans un problème GitHub, un e-mail, etc.

   

4. Si Visual Studio cesse de répondre ou si vous n’êtes pas en mesure d’accéder à la fenêtre Sortie , redémarrez Visual Studio, ouvrez une fenêtre de commande et entrez la commande suivante :

   DebugAdapterHost.Logging /On
   

5. Commencez le débogage et reproduisez votre problème. Les journaux du débogueur se trouvent dans %temp%\DebugAdapterHostLog.txt.

Voir aussi

Pour plus d’informations sur le débogueur Visual Studio, consultez l’article Débogage dans Visual Studio.