Déboguer votre code Python dans Visual Studio

Visual Studio offre une expérience de débogage complète pour Python. Dans cet article, vous allez découvrir comment attacher le débogueur à des processus en cours et évaluer des expressions dans les fenêtres Surveiller et Immédiat. Dans le débogueur, vous pouvez inspecter les variables locales, utiliser des points d'arrêt, exécuter pas à pas les instructions (entrer/sortir/suivre), Définir l'Instruction Suivante, etc.

Pour plus d’informations sur le débogage spécifique au scénario, consultez les articles suivants :

Prerequisites

Déboguer du code avec ou sans projet

Si vous souhaitez contrôler votre environnement et vos arguments Python, commencez par créer un projet pour votre code. Vous pouvez créer un projet avec le modèle de projet From existing Python code. Pour plus d’informations, consultez Créer un projet à partir de fichiers de code Python existants.

Toutefois, vous n'avez pas besoin d'un fichier projet ou solution dans Visual Studio pour déboguer votre code Python. Pour déboguer du code dans un fichier de Python autonome, ouvrez votre fichier dans Visual Studio, puis sélectionnez Debug>Déboguer. Visual Studio lance le script avec l’environnement global par défaut et aucun argument. Vous disposez ensuite d’une prise en charge intégrale du débogage pour votre code. Pour plus d’informations, consultez Python environnements.

Explorer le débogage de base

Le flux de travail de débogage de base implique la définition de points d'arrêt, l'exécution pas à pas du code, l’inspection des valeurs et la gestion des exceptions. Vous pouvez démarrer une session de débogage en sélectionnant Déboguer>Démarrer le débogage ou utilisez le raccourci clavier F5. Pour un project, ces actions lancent le fichier startup avec l'environnement actif du project et tous les arguments de ligne de commande ou chemins de recherche spécifiés pour Project Propriétés. Pour configurer les propriétés, consultez Définir les options de débogage de projet.

Définir le fichier de démarrage du projet

Le fichier de démarrage d’un projet est affiché en gras dans Explorateur de solutions. Vous pouvez choisir le fichier à utiliser comme fichier de démarrage.

  • Pour spécifier un fichier projet comme fichier de démarrage, cliquez avec le bouton droit sur le fichier, puis sélectionnez Définir comme élément de démarrage.

Dans Visual Studio 2017 version 15.6 et ultérieure, vous voyez une alerte si vous n'avez pas de jeu de fichiers de démarrage spécifié. Les versions antérieures de Visual Studio peuvent ouvrir une fenêtre Output avec l’interpréteur Python en cours d’exécution, ou la fenêtre Output s’ouvre et se ferme brièvement.

Spécifier l’environnement actif

Si vous utilisez un fichier projet, le débogueur commence toujours par l'environnement de Python actif pour le projet. Vous pouvez modifier l’environnement actif actuel. Pour plus d’informations, consultez Select a Python environment for a project.

Si vous déboguez un fichier de code Python autonome, Visual Studio lance le script avec l'environnement global par défaut et aucun argument.

Définir des points d’arrêt

Les points d’arrêt arrêtent l’exécution du code à un point marqué pour vous permettre d’inspecter l’état du programme.

Certains points d’arrêt dans Python peuvent être surprenants pour les développeurs qui ont travaillé avec d’autres langages de programmation. Dans Python, l'intégralité du fichier est du code exécutable. Par conséquent, Python exécute le fichier lorsqu'il est chargé pour traiter toutes les définitions de classe ou de fonction de niveau supérieur. Si un point d'arrêt est défini, vous pourriez constater que le débogueur interrompt l'exécution au milieu d'une déclaration de classe. Ce comportement est correct, même s’il est parfois surprenant.

  • Pour définir un point d’arrêt, sélectionnez dans la marge gauche de l’éditeur de code ou cliquez avec le bouton droit sur une ligne de code et sélectionnezPoint 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 cliquez avec le bouton droit sur la ligne de code et sélectionnezPoint d’arrêt Supprimer le > d’arrêt. Vous pouvez également désactiver un point d'arrêt en sélectionnant le point rouge, puis en sélectionnant Point d'arrêt>Désactiver le point d'arrêt.

    Screenshot qui montre comment désactiver un point d’arrêt dans la marge gauche du fichier de code dans Visual Studio.

Définir des conditions et des actions

Vous pouvez personnaliser les conditions dans lesquelles un point d’arrêt est déclenché, par exemple uniquement lorsqu'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 Conditions. La boîte de dialogue Paramètres de point d'arrêt s’ouvre.

    Dans la boîte de dialogue, vous pouvez ajouter plusieurs conditions et créer des expressions conditionnelles à l’aide de Python code. Pour plus d’informations sur cette fonctionnalité dans Visual Studio, consultez les conditions Breakpoint.

  • Vous avez également les options permettant de définir des actions pour un point d’arrêt. Vous pouvez créer un message pour vous connecter à la fenêtre Sortie et spécifier éventuellement pour continuer l’exécution automatiquement.

    La journalisation d’un message crée un point de trace qui n’ajoute pas de code de journalisation directement à votre application.

Selon la façon dont vous configurez des conditions et des actions pour un point d’arrêt, l’icône rouge dans la marge gauche change pour indiquer vos paramètres. Vous pouvez voir la forme de point, un minuteur d’horloge ou un diamant.

Parcourir le code pas à pas

Lorsque Visual Studio arrête l’exécution du code à un point d’arrêt, il existe plusieurs commandes que vous pouvez utiliser pour parcourir votre code ou exécuter des blocs de code avant de rompre à nouveau. Les commandes sont disponibles à quelques endroits dans Visual Studio, notamment la barre d’outils du débogueur, le menu de débogage, le menu contextuel en cliquant avec le bouton droit dans l’éditeur de code et via les raccourcis clavier.

Le tableau suivant récapitule ces commandes et fournit le raccourci clavier :

Command Shortcut Description
Arrêter Maj + F5 Arrêtez la session de débogage.
Restart Ctrl + Maj + F5 Redémarrez la session de débogage actuelle.
Continuer F5 Exécutez le code jusqu’à atteindre le point d’arrêt suivant.
Entrez dans F11 Exécutez l’instruction suivante et arrêtez. Si l’instruction suivante 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écutez l’instruction suivante, notamment en effectuant un appel à une fonction (exécutant tout son code) et en appliquant n’importe quelle valeur de retour. Cette commande vous permet d’ignorer facilement les fonctions que vous n’avez pas besoin de déboguer.
Pas à pas sortant Maj+F11 Exécutez le code jusqu’à la fin de la fonction active, puis passez à l’instruction appelante. Cette commande est utile lorsque vous n’avez pas besoin de déboguer le reste de la fonction actuelle.
Exécuter jusqu’au curseur Ctrl+F10 Exécutez le code jusqu’à l’emplacement du caret 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 Déplacez le point d'arrêt actuel dans le code à l'emplacement du curseur. Cette commande vous permet d’omettre un segment de code d’être exécuté du tout, par exemple lorsque vous savez que le code est défectueux ou produit un effet secondaire indésirable.
Afficher l’instruction suivante Alt+Num+\ Revenez à l’instruction suivante à exécuter dans le code. Cette commande vous aide à localiser l’emplacement dans votre code où le débogueur est arrêté.

Inspecter et modifier des 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 surveiller des variables individuelles et des expressions personnalisées. Pour plus d’informations, consultez Inspecter les variables.

  • Pour afficher une valeur à l’aide de la fonctionnalité DataTips pendant le débogage, pointez 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 Autos, sélectionnez Debug>Windows>Autos. Cette fenêtre contient des variables et des expressions proches de l’instruction actuelle. Vous pouvez double-cliquer dans la colonne valeur ou sélectionner et entrer F2 pour modifier la valeur :

    Capture d'écran montrant la fenêtre Autos dans le débogueur Visual Studio.

    Pour plus d’informations sur l’utilisation de la fenêtre Autos , consultez Inspecter les variables dans les fenêtres Autos et Locals.

  • Pour utiliser la fenêtre Locals, sélectionnez Debug>Windows>Locals. Cette fenêtre affiche toutes les variables qui se trouvent dans l’étendue actuelle. Vous pouvez double-cliquer dans la colonne valeur ou sélectionner et entrer F2 pour modifier la valeur :

    Pour plus d’informations sur l’utilisation de la fenêtre Locals , consultez Inspecter les variables dans les fenêtres Autos et Locals.

  • Pour utiliser les fenêtres Watch, sélectionnez Debug>Windows>Watch>Watch 1-4. Cette option vous permet d’entrer des expressions Python arbitraires et d’afficher les résultats. Les expressions sont réévaluées pour chaque étape :

    Pour plus d’informations sur l’utilisation de la fenêtre Surveiller, consultez Définir une surveillance sur les variables avec les fenêtres Surveiller et Surveiller rapide.

  • Pour inspecter une valeur de chaîne, sélectionnez Affichage (loupe) sur le côté droit de l’entrée Valeur . Les types str, unicode, bytes et bytearray sont tous disponibles pour l’inspection.

    Le menu déroulant Affichage affiche quatre options de visualisation : Texte, HTML, XML ou JSON.

    Une fois que vous avez sélectionné une visualisation, une boîte de dialogue contextuelle affiche la valeur de chaîne non mise en guillemet en fonction du type sélectionné. Vous pouvez afficher la chaîne de caractères avec l'habillage et le défilement, la mise en surbrillance de la syntaxe et les vues en arborescence. Ces visualisations peuvent aider à déboguer des problèmes avec des chaînes longues et complexes.

Afficher les exceptions

Si une erreur se produit dans votre programme pendant le débogage, mais que vous ne disposez pas d’un gestionnaire d’exceptions pour celui-ci, le débogueur s’arrête au point de l’exception :

Capture d'écran qui affiche une fenêtre contextuelle d'exception pour une erreur non gérée dans le débogueur Visual Studio.

Capture d'écran montrant une fenêtre contextuelle d'exception pour une erreur non gérée dans le débogueur Visual Studio.

Lorsqu’une erreur se produit, vous pouvez inspecter l’état actuel du programme, y compris la pile des appels. Toutefois, si vous parcourez le code, le processus de débogage continue de lever l’exception jusqu’à ce qu’elle soit gérée ou que votre programme se termine.

  • Pour afficher une vue étendue des exceptions, sélectionnez Debug>Windows>Exception Settings.

    Dans la fenêtre Paramètres des exceptions , la case à cocher située en regard d’une exception contrôle si le débogueur s’arrête toujours lorsque cette exception est levée.

  • Pour interrompre plus souvent une exception particulière, cochez la case en regard de l’exception dans la fenêtre Paramètres d’exception .

  • Par défaut, la plupart des exceptions s’arrêtent lorsqu’un gestionnaire d’exceptions est introuvable dans le code source. Pour modifier ce comportement, cliquez avec le bouton droit sur n’importe quelle exception et modifiez l’option Continuer quand le code utilisateur n’est pas géré . Pour interrompre moins souvent lorsqu'une exception se produit, désélectionnez cette option.

  • Pour configurer une exception qui n’apparaît pas dans la fenêtre Paramètres d’exception , sélectionnez Ajouter (symbole plus). Entrez un nom pour l’exception à surveiller. Le nom doit correspondre au nom complet de l’exception.

Configurer les options de débogage de projet

Par défaut, le débogueur démarre votre programme avec le lanceur Python standard, aucun argument de ligne de commande et aucun autre chemin d’accès ou conditions spéciaux. Vous pouvez configurer les options de démarrage d’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 Properties, puis sélectionnez l’onglet Debug.

Les sections suivantes décrivent les propriétés spécifiques.

Définir le comportement de lancement

Le tableau suivant répertorie les valeurs possibles pour la propriété launch mode . Utilisez cette propriété pour définir le comportement de lancement du débogueur.

Valeur Description
Lanceur Python standard Utilisez le code de débogage écrit dans des Python portables compatibles avec CPython, IronPython et des variantes comme stackless Python. Cette option offre la meilleure expérience pour le débogage du code pur Python. Lorsque vous attachez à un processus en cours d’exécution python.exe , le lanceur spécifié dans cette propriété est utilisé. Ce lanceur fournit également le débogage en mode mixte pour CPython, ce qui vous permet de déboguer pas à pas entre le code C/C++ et le code Python.
Lanceur web Démarrez votre navigateur par défaut lors du lancement et activez le débogage des modèles. Pour plus d’informations, consultez la section débogage du modèle web .
Lanceur web Django Implémentez un comportement identique à la propriété du lanceur Web , mais pour un environnement Django. Utilisez cette option uniquement à des fins de compatibilité descendante.
lanceur pour IronPython (.NET) Utilisez le débogueur .NET, qui fonctionne uniquement avec IronPython, mais permet d’effectuer un pas à pas entre n’importe quel projet de langage .NET, y compris C# et Visual Basic. Ce lanceur est utilisé si 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 en cours d’exécution pour le débogueur.

Propriété Description
Chemins de recherche Spécifiez les chemins de recherche de fichiers et de dossiers Visual Studio utiliser pour votre projet. Ces valeurs correspondent aux éléments affichés dans le nœud Search Paths 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 formulaire relatif.
Script Arguments Définissez les arguments à ajouter à la commande Visual Studio utilise pour lancer votre script et apparaissent après le nom de fichier de votre script. Le premier élément répertorié dans la valeur est disponible pour votre script en tant que sys.argv[1], le deuxième comme sys.argv[2], et ainsi de suite.
Arguments de l’interpréteur Répertoriez les arguments à ajouter à la ligne de commande du lanceur avant le nom de votre script. Les arguments courants sont -W ... de contrôler les avertissements, -O d’optimiser légèrement votre programme et -u d’utiliser des E/S sans débogage. Les utilisateurs ironPython sont susceptibles d’utiliser ce champ pour passer des -X options, telles que -X:Frames ou -X:MTA.
Chemin de l’interpréteur Identifiez un chemin d’accès 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 du formulaire <NAME>=\<VALUE>. Visual Studio applique cette valeur de propriété en dernier, au-dessus de toutes les variables d’environnement globales existantes, et après PYTHONPATH est défini en fonction du paramètre Search Paths. Par conséquent, ce paramètre peut être utilisé pour remplacer manuellement l’une de ces autres variables.

Utiliser des fenêtres interactives

Il existe deux fenêtres interactive que vous pouvez utiliser pendant une session de débogage : la fenêtre standard Visual Studio Immediate et la fenêtre Python Debug Interactive.

Ouvrir la fenêtre immédiate

Vous pouvez utiliser la fenêtre standard Visual Studio Immediate pour évaluer rapidement les expressions Python et inspecter ou affecter des variables dans votre programme en cours d’exécution. Pour plus d’informations, consultez la fenêtre Immédiate.

  • Pour ouvrir la fenêtre Immediate, sélectionnez Debug>Windows>Immediate. Vous pouvez également utiliser le raccourci clavier Ctrl Alt++I.

Ouvrir la fenêtre Debug Interactive

La fenêtre Débogueur interactif Python offre un environnement riche, avec l’expérience complète du REPL interactif disponible lors du débogage, y compris la rédaction et l’exécution de code. Cette fenêtre se connecte automatiquement à tout processus démarré dans le débogueur à l’aide du lanceur de Python Standard, y compris les processus attachés via Debug>Attach à Process. Toutefois, cette fenêtre n’est pas disponible lors de l’utilisation du débogage C/C++ en mode mixte.

  • Pour utiliser la fenêtre Debug Interactive, sélectionnez Debug>Windows>Python Debug Interactive (Shift+Alt+I).

La fenêtre Debug Interactive prend en charge les méta-commandes spéciales en plus des commandes REPL standard, comme décrit dans le tableau suivant :

Command Description
$continue, $cont, $c Commencez à exécuter le programme à partir de l’instruction actuelle.
$down, $d Déplacez le cadre actuel un niveau vers le bas dans la trace de la pile.
$frame Affichez l’ID de frame actuel.
$frame Basculez l’image actuelle vers l’ID d’image spécifié.
- Nécessite un <argument d’ID de trame>.
$load Chargez les commandes à partir du fichier et exécutez jusqu’à la fin.
$proc Affichez l’ID de processus actuel.
$proc Basculez le processus actuel vers l’ID de processus spécifié.
- Nécessite un <argument d’ID> de processus.
$procs Répertoriez les processus en cours de débogage.
$stepin, $step, $s Passez à l’appel de fonction suivant, si possible.
$stepout, $return, $r Quittez la fonction actuelle.
$stepover, $until, $unt Ignorer l’appel de fonction suivant.
$thread Affichez l’ID de thread actuel.
$thread Basculez le thread actuel vers l’ID de thread spécifié.
- Nécessite un <argument d’ID> de thread.
$threads Répertoriez les threads en cours de débogage.
$up, $u Déplacez le cadre actuel d’un niveau dans la trace de la pile.
$where, $w, $bt Répertoriez les trames 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 . Si vous modifiez le processus actif, le thread ou le frame dans la fenêtre Debug Interactive , les autres fenêtres du débogueur ne sont pas affectées. De même, la modification du processus actif, du thread ou du frame 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 devrez peut-être utiliser le débogueur hérité :

  • 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
  • ptvsd 3.x et versions antérieures de 4.x

Le débogueur hérité est utilisé par défaut dans Visual Studio 2017 version 15.7 et dans les versions antérieures.

  • Pour utiliser le débogueur hérité, sélectionnez Tools>Options, développez les options Python>Debugging, puis sélectionnez l’option Utiliser le débogueur hérité.

Prise en charge des versions antérieures de Visual Studio ou de Python

Visual Studio 2017 version 15.8 et ultérieures utilisent un débogueur basé sur ptvsd version 4.1 et ultérieure. Visual Studio 2019 version 16.5 et versions 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 exécutez 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, Debugger ne prend pas en charge cet environnement Python :

Capture d'écran du message d'erreur du débogueur « 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 hérité.

Prendre en charge les versions antérieures de ptvsd

Si vous utilisez une version antérieure de ptvsd dans l'environnement actuel (par exemple, une version 4.0.x antérieure ou une version 3.x requise pour le débogage à distance), Visual Studio peut afficher une erreur ou un avertissement.

Si votre environnement utilise ptvsd 3.x, Visual Studio affiche l’erreur, PackageDebugger n’a pas pu être chargé :

Capture d’écran du message d’erreur du débogueur « Impossible de charger le package du débogueur ».

L’avertissement, le package de débogueur est obsolète, s’affiche lorsque vous utilisez une version 4.x antérieure de ptvsd :

Capture d’écran du message d’avertissement du débogueur « Le package du débogueur est obsolète ».

Lorsque Visual Studio signale ces erreurs d’environnement, vous devez utiliser le débogueur hérité.

Important

Bien que vous choisissiez d’ignorer l’avertissement pour certaines versions de ptvsd, Visual Studio ne fonctionne pas correctement.

Gérer votre installation ptvsd

Procédez comme suit pour gérer votre installation ptvsd :

  1. Dans la fenêtre Python Environnements, accédez à l’onglet Packages.

  2. Entrez ptvsd dans la zone de recherche et examinez la version installée de ptvsd :

  3. Si la version est inférieure à la version 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 ensuite sa version groupée. (Vous pouvez également désinstaller à partir de PowerShell à l’aide de la pip uninstall ptvsd commande.)

  4. Vous pouvez également mettre à jour le package ptvsd vers sa version la plus récente en suivant les instructions de la section Résoudre les problèmes liés aux scénarios de débogage .

Résoudre les problèmes liés aux scénarios de débogage

Les scénarios suivants décrivent d’autres options de résolution des problèmes 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 antérieures, commencez par mettre à niveau votre version du débogueur comme suit :

  1. Dans la fenêtre Python Environnements, accédez à l’onglet Packages.

  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.)

    Capture d'écran montrant comment sélectionner la commande de mise à niveau ptvsd dans la fenêtre Environnements Python.

    Si des problèmes persistent, déposez un problème sur le dépôt PTVS GitHub.

    Remarque

    Pour Visual Studio 2019 version 16.5 et ultérieures, debugpy fait partie de la charge de travail Python de Visual Studio et est mis à jour avec Visual Studio.

Activer la journalisation du débogueur

Lors de l’examen d’un problème de débogueur, Microsoft pouvez vous demander d’activer et de collecter les journaux du débogueur pour faciliter le diagnostic.

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

  1. Ouvrez une fenêtre de commande dans Visual Studio en sélectionnant View>Other Windows>Command Window.

  2. Entrez la commande suivante :

    DebugAdapterHost.Logging /On /OutputWindow

  3. Démarrez le débogage et passez par les étapes nécessaires pour reproduire votre problème. Pendant ce temps, les journaux de débogage apparaissent dans la fenêtre Sortie sous Journal hôte de l’adaptateur de débogage. Vous pouvez ensuite copier les logs à partir de cette fenêtre et les coller dans un problème de GitHub, dans un e-mail, et ainsi de suite.

  4. Si Visual Studio cesse de répondre ou si vous ne parvenez pas à accéder à la fenêtre Output, redémarrez Visual Studio, ouvrez une fenêtre de commande et entrez la commande suivante :

    DebugAdapterHost.Logging /On

  5. Commencez à déboguer et reproduire à nouveau votre problème. Les journaux du débogueur se trouvent dans %temp%\DebugAdapterHostLog.txt.

Contenu connexe

  • Last updated on