Depuración del código de Python en Visual Studio

Visual Studio proporciona una experiencia de depuración completa para Python. En este artículo, explorará cómo asociar el depurador a procesos en ejecución y evaluar expresiones en las ventanas Inspección e Inmediato. En el depurador, puede inspeccionar variables locales, usar puntos de interrupción, introducir/salir/omitir instrucciones, Definir instrucción siguiente, etc.

Para obtener información sobre depuración en escenarios específicos, consulte los siguientes artículos:

• Depuración remota de Linux
• Mixed-mode Python/C++ debugging (Depuración en modo mixto Python/C++)
• Symbols for mixed-mode debugging (Símbolos de depuración en modo mixto)

Requisitos previos

• Visual Studio instalado con compatibilidad con cargas de trabajo de Python. Para obtener más información, consulte Instalación de la compatibilidad con Python en Visual Studio.

• Código de Python que se va a usar con el depurador.

Código de depuración con o sin un proyecto

Si desea controlar el entorno y los argumentos de Python, cree primero un proyecto para el código. Puede crear un proyecto con la plantilla de proyecto Desde código de Python existente. Para obtener más información, consulte Creación de un proyecto a partir de archivos de código fuente de Python existentes.

Sin embargo, no necesita un archivo de proyecto o solución en Visual Studio para depurar el código de Python. Para depurar código en un archivo de Python independiente, abra el archivo en Visual Studio y seleccione Depurar>Iniciar depuración. Visual Studio inicia el script con el entorno predeterminado global y sin argumentos. A continuación, tiene compatibilidad completa con la depuración para el código. Para obtener más información, vea Entornos de Python.

Exploración de la depuración básica

El flujo de trabajo de depuración básica conlleva configurar puntos de interrupción, recorrer paso a paso el código, inspeccionar valores y administrar excepciones. Para iniciar una sesión de depuración, seleccione Depurar>Iniciar depuración o use el método abreviado de teclado F5. Para un proyecto, estas acciones inician el archivo de inicio con el entorno activo del proyecto y cualquier argumento de línea de comandos o rutas de búsqueda especificadas para Propiedades del proyecto. Para configurar las propiedades, consulte Definición de opciones de depuración de proyectos.

Definición del archivo de inicio del proyecto

El archivo de inicio para un proyecto se muestra en negrita en el Explorador de soluciones. Puede elegir qué archivo se va a usar como archivo de inicio.

• Para especificar un archivo de proyecto como archivo de inicio, haga clic con el botón derecho en el archivo y seleccione Establecer como elemento de inicio.

En Visual Studio 2017, versión 15.6 y posteriores, verá una alerta si no tiene establecido un archivo de inicio especificado. Las versiones anteriores de Visual Studio pueden abrir una ventana de Salida con el intérprete de Python en ejecución o la ventana de Salida se abre y cierra brevemente.

Especificación del entorno activo

Si usa un archivo de proyecto, el depurador siempre comienza con el entorno de Python activo para el proyecto. Puede cambiar el entorno activo actual. Para obtener más información, consulte Selección de un entorno de Python para un proyecto.

Si va a depurar un archivo de código de Python independiente, Visual Studio inicia el script con el entorno predeterminado global y sin argumentos.

Establecimiento de puntos de interrupción

Los puntos de interrupción detienen la ejecución del código en un punto especificado, a fin de poder inspeccionar el estado del programa.

Algunos puntos de interrupción de Python pueden resultar sorprendentes para aquellos desarrolladores que hayan trabajado con otros lenguajes de programación. En Python, todo el archivo es código ejecutable, por lo que Python ejecuta el archivo cuando se carga para procesar cualquier definición de clase o función de nivel superior. Si se ha establecido un punto de interrupción, puede observar que el depurador se interrumpe parcialmente a través de una declaración de clase. Este comportamiento es correcto, aunque a veces sea sorprendente.

• Para establecer un punto de interrupción, seleccione en el margen izquierdo del editor de código o haga clic con el botón derecho en una línea de código y seleccione Punto de interrupción>Insertar punto de interrupción. En cada línea que tiene definido un punto de interrupción, aparece un punto rojo.

  

• Para eliminar un punto de interrupción, seleccione el punto rojo o haga clic con el botón derecho en la línea de código y seleccione Punto de interrupción>Eliminar punto de interrupción. También puede deshabilitar un punto de interrupción seleccionando el punto rojo y seleccionando Punto de interrupción>Deshabilitar punto de interrupción.

  

Definición de condiciones y acciones

Puede personalizar las condiciones en que se desencadena un punto de interrupción, como que la interrupción se lleve a cabo cuando una variable se establece en un valor concreto o en un intervalo de valor.

• Para definir condiciones, haga clic con el botón derecho en el punto rojo del punto de interrupción y seleccione Condiciones. Se abre el cuadro de diálogo Configuración de punto de interrupción.

  En el cuadro de diálogo, puede agregar varias condiciones y crear expresiones condicionales mediante código de Python. Para obtener todos los detalles sobre esta característica de Visual Studio, vea Breakpoint conditions (Condiciones de los puntos de interrupción).

  

• También tiene las opciones para definir Acciones para un punto de interrupción. Puede crear un mensaje para iniciar sesión en la ventana Salida y, opcionalmente, especificar para continuar la ejecución automáticamente.

  

  Al registrar un mensaje se crea un punto de seguimiento que no agrega código de registro directamente a la aplicación.

En función de cómo configure las condiciones y acciones de un punto de interrupción, el icono rojo del margen izquierdo cambia para indicar la configuración. Es posible que vea la forma de punto, un temporizador de reloj o un diamante.

Examinar el código

Cuando Visual Studio detiene la ejecución de código en un punto de interrupción, hay varios comandos que puede usar para recorrer el código o ejecutar bloques de código antes de interrumpir de nuevo. Los comandos están disponibles en algunos lugares de Visual Studio, incluida la barra de herramientas Depurador, el menú Depurar, el menú contextual del editor de código y a través de métodos abreviados de teclado.

En la tabla siguiente se resumen estos comandos y se proporciona el método abreviado de teclado:

Comando	Acceso directo	Descripción
Detención	Mayús + F5	Detenga la sesión de depuración.
Restart (Reiniciar)	Ctrl+Mayús+F5	Reinicie la sesión de depuración actual.
Continuar	F5	Ejecuta código hasta que alcanza el punto de interrupción siguiente.
Depurar paso a paso por instrucciones	F11	Ejecuta la instrucción siguiente y se detiene. Si la siguiente instrucción es una llamada a una función, el depurador se detiene en la primera línea de la función que se ha llamado.
Paso a paso por procedimientos	F10	Ejecuta la siguiente instrucción, como realizar una llamada a una función (mediante la ejecución de todo su código) y aplicar cualquier valor devuelto. Este comando le permite omitir con facilidad aquellas funciones que no necesita depurar.
Paso a paso para salir	Mayús+F11	Ejecuta el código hasta el final de la función actual y después pasa a la instrucción de llamada. Este comando resulta útil cuando no necesita depurar el resto de la función actual.
Ejecutar hasta el cursor	Ctrl+F10	Ejecuta el código hasta la ubicación del operador exponencial en el editor. Este comando le permite saltar fácilmente un segmento de código que no necesita depurar.
Establecer instrucción siguiente	Ctrl+Mayús+F10	Cambia el punto de ejecución actual del código a la ubicación del operador exponencial. Este comando le permite omitir por completo la ejecución de un segmento de código, por ejemplo, cuando sabe que el código es erróneo o que produce un efecto secundario no deseado.
Mostrar la instrucción siguiente	Alt+Núm+\	Vuelve a la siguiente instrucción para que se ejecute en el código. Este comando le ayuda a localizar el lugar en el código donde se detiene el depurador.

Inspeccionar y modificar valores

Al detener la ejecución del código en el depurador, puede inspeccionar y modificar los valores de variables. También puede usar la ventana Inspección para supervisar variables individuales y expresiones personalizadas. Para obtener más información, consulte Inspección de variables.

• Para ver un valor con la función DataTips durante la depuración, mantenga el puntero sobre cualquier variable en el editor. Puede seleccionar el valor de la variable para cambiarlo:

  

• Para usar la ventana Automático, seleccione Depurar>Ventanas>Automático. Esta ventana contiene variables y expresiones cercanas a la instrucción actual. Puede hacer doble clic en la columna de valor o seleccionar y pulsar F2 para modificar el valor:

  

  Para obtener más información sobre cómo usar la ventana Automático, consulte Inspección de variables en las ventanas Automático y Locales.

• Para usar la ventana Locales, seleccione Depurar>Ventanas>Locales. Esta ventana muestra todas las variables que se encuentran en el ámbito actual, que se pueden volver a modificar:

  

  Para obtener más información sobre cómo usar la ventana Locales, consulte Inspección de variables en las ventanas Automático y Locales.

• Para usar las ventanas Inspección, seleccione Depurar>Ventanas>Inspección>Inspección 1-4. Esta opción permite escribir expresiones arbitrarias de Python y ver los resultados. Las expresiones se vuelven a evaluar para cada paso:

  

  Para obtener más información sobre cómo utilizar la ventana Inspección, consulte Definición de una inspección en variables con las ventanas Inspección e Inspección rápida.

• Para inspeccionar un valor de cadena, seleccione Ver (lupa) en el lado derecho de la entrada Valor. Todos los tipos str, unicode, bytes y bytearray están disponibles para su inspección.

  El menú desplegable Ver muestra cuatro opciones de visualización: Texto, HTML, XML o JSON.

  

  Después de seleccionar una visualización, un cuadro de diálogo emergente muestra el valor de cadena sin comillas según el tipo seleccionado. Puede ver la cadena con ajuste y desplazamiento, resaltado de sintaxis y vistas de árbol. Estas visualizaciones pueden ayudar a depurar problemas con cadenas largas y complejas.

Visualización de excepciones

Si se produce algún error en su programa durante la depuración, pero no dispone de un controlador de excepciones para él, el depurador se interrumpe en el punto de la excepción:

Cuando se produce un error, puede inspeccionar el estado actual del programa, incluida la pila de llamadas. Sin embargo, si intenta recorrer el código, el proceso de depuración continúa para lanzar la excepción hasta que se controla o hasta que el programa se cierra.

• Para ver una vista expandida de excepciones, seleccione Depurar>Ventanas>Configuración de excepciones.

  

  En la ventana Configuración de excepciones, la casilla situada junto a una excepción controla si el depurador siempre se interrumpe cuando se produce esa excepción.

• Para interrumpir con más frecuencia una excepción determinada, active la casilla situada junto a la excepción en la ventana Configuración de excepciones.

• De manera predeterminada, la mayoría de las excepciones activan una interrupción cuando no se puede encontrar un controlador de excepciones en el código fuente. Para cambiar este comportamiento, haga clic con el botón derecho en cualquier excepción y modifique la opción Continuar cuando no se controle en el código de usuario. Para interrumpir la excepción con menos frecuencia, desmarque esta opción.

• Para configurar una excepción que no aparece en la ventana Configuración de excepciones, seleccione Agregar (símbolo más). Escriba un nombre para la excepción que se va a inspeccionar. El nombre debe coincidir con el nombre completo de la excepción.

Configuración de opciones de depuración del proyecto

De forma predeterminada, el depurador inicia el programa con el selector de Python estándar, sin argumentos de línea de comandos ni otras rutas de acceso o condiciones especiales. Puede configurar las opciones de inicio de un proyecto de Python estableciendo las propiedades de depuración.

• Para acceder a las propiedades de depuración de un proyecto, haga clic con el botón derecho en el proyecto de Python en el Explorador de soluciones, seleccione Propiedades y, a continuación, seleccione la pestaña Depurar.

  

En las secciones siguientes se describen las propiedades específicas.

Definición del comportamiento de inicio

En la tabla siguiente se enumeran los valores posibles de la propiedad Modo de inicio. Use esta propiedad para definir el comportamiento de inicio del depurador.

Valor	Descripción
Iniciador de Python estándar	Utiliza código de depuración escrito en Portable Python compatible con CPython, IronPython y variantes, como Stackless Python. Esta opción proporciona la mejor experiencia de depuración de código Python puro. Al realizar una asociación a un proceso python.exe en ejecución, se usa el iniciador especificado en esta propiedad. Este iniciador también proporciona depuración en modo mixto para CPython, lo que permite cambiar sin problemas entre los códigos C/C++ y Python.
Iniciador web	Inicia el explorador predeterminado al inicio y habilita la depuración de plantillas. Para obtener más información, consulte la sección Depuración de plantillas web.
Iniciador web de Django	Implementa un comportamiento idéntico a la propiedad Iniciador web, pero para un entorno Django. Utilice esta opción solo para fines de compatibilidad con versiones anteriores.
Iniciador de IronPython (.NET)	Usa el depurador de .NET, que solo funciona con IronPython, pero permite cambiar entre cualquier proyecto en lenguaje .NET, incluidos C# y Visual Basic. Este iniciador se usa para establecer una asociación con un proceso .NET en ejecución que hospeda IronPython.

Definición del comportamiento de ejecución

En la tabla siguiente se describen las propiedades que puede definir para configurar el comportamiento en ejecución del depurador.

Propiedad	Descripción
Rutas de búsqueda	Especifique las rutas de búsqueda de archivos y carpetas que Visual Studio usa para el proyecto. Estos valores coinciden con los elementos que se muestran en el nodo Rutas de búsqueda del proyecto en el Explorador de soluciones. Aunque puede especificar rutas de acceso de búsqueda en este cuadro de diálogo, puede ser más fácil usar el Explorador de soluciones, donde puede examinar carpetas y convertir automáticamente rutas de acceso al formato correspondiente.
Argumentos de script	Define los argumentos que se van a agregar al comando que Visual Studio usa para iniciar el script y que aparecen después del nombre de archivo del script. El primer elemento que aparece en valor está disponible para el script como sys.argv[1], el segundo como sys.argv[2], y así sucesivamente.
Argumentos del intérprete	Enumera los argumentos que se van a agregar a la línea de comandos del iniciador antes del nombre del script. Los argumentos comunes son -W ... para controlar advertencias, -O para optimizar ligeramente el programa y -u para utilizar E/S no almacenada en el búfer. Los usuarios de IronPython probablemente usen este campo para pasar opciones -X, como -X:Frames o -X:MTA.
Ruta del intérprete	Identifica una ruta de acceso del intérprete para invalidar la ruta de acceso asociada al entorno actual. El valor puede ser útil para iniciar el script con un intérprete no estándar.
Variables de entorno	Use esta propiedad para agregar entradas con formato <NAME>=\<VALUE>. Visual Studio aplica este valor de propiedad el último, encima de cualquier variable de entorno global existente y después de que PYTHONPATH se establezca según la configuración de Rutas de búsqueda. Como resultado, esta configuración se puede usar para invalidar manualmente cualquiera de esas otras variables.

Trabajo con ventanas interactivas

Existen dos ventanas interactivas que puede usar durante una sesión de depuración: la ventana Inmediato estándar de Visual Studio y la ventana Interactiva de depuración de Python.

Apertura de la ventana Inmediato

Puede usar la ventana Inmediato de Visual Studio estándar para evaluar rápidamente las expresiones de Python e inspeccionar o asignar variables en el programa en ejecución. Para obtener más información, consulte Ventana Inmediato.

• Para abrir la ventana Inmediato, seleccione Depurar>Ventanas>Inmediato. También puede usar el método abreviado de teclado Ctrl+Alt+I.

Apertura de la ventana Interactiva de depuración

La ventana Interactiva de depuración de Python ofrece un entorno enriquecido con la experiencia completa de REPL interactivo disponible durante la depuración, incluida la escritura y ejecución de código. Esta ventana se conecta automáticamente a cualquier proceso iniciado en el depurador mediante el iniciador de Python estándar, incluidos los procesos asociados mediante Depurar>Asociar al proceso. No obstante, esta ventana no está disponible si se usa la depuración en modo mixto de C/C++.

• Para usar la ventana Interactiva de depuración, seleccione Depurar>Ventanas>Interactiva de depuración de Python (Mayús+Alt+I).

  

La ventana Interactiva de depuración admite metacomandos especiales además de los comandos REPL estándar, como se describe en la tabla siguiente:

Comando	Descripción
$continue, $cont, $c	Inicia la ejecución del programa a partir de la instrucción actual.
$down, $d	Baja el marco actual un nivel en el seguimiento de la pila.
$frame	Muestra el identificador del marco actual.
$frame	Cambia el marco actual al identificador del marco especificado. - Requiere un argumento <frame ID>.
$load	Carga los comandos del archivo y los ejecuta hasta que terminan.
$proc	Muestra el identificador de proceso actual.
$proc	Cambia el proceso actual al identificador de proceso especificado. - Requiere un argumento <process ID>.
$procs	Enumera los procesos que se están depurando actualmente.
$stepin, $step, $s	Avanza a la siguiente llamada de función, si es posible.
$stepout, $return, $r	Sale de la función actual.
$stepover, $until, $unt	Omite la siguiente llamada de función.
$thread	Muestra el identificador de subproceso actual.
$thread	Cambia el subproceso actual al identificador de subproceso especificado. - Requiere un argumento <thread ID>.
$threads	Enumera los subprocesos que se están depurando actualmente.
$up, $u	Sube el marco actual un nivel en el seguimiento de la pila.
$where, $w, $bt	Enumera los marcos del subproceso actual.

Las ventanas estándar del depurador, como Procesos, Subprocesos y Pila de llamadas, no están sincronizadas con la ventana Interactiva de depuración. El cambio del marco, subproceso o proceso activo en la ventana Interactiva de depuración no afecta a las otras ventanas del depurador. Del mismo modo, el cambio del marco, subproceso o proceso activo en las otras ventanas del depurador no afecta a la ventana Interactiva de depuración.

Usar el depurador heredado

En función de la configuración del entorno, es posible que tenga que usar el depurador heredado:

• Visual Studio 2017, versión 15.7 y anteriores con Python 2.6, 3.1 a 3.4 o IronPython
• Visual Studio 2019, versión 16.5 y posteriores con Python 2.6, 3.1 a 3.4 o IronPython
• ptvsd 3.x y versiones anteriores de 4.x

El depurador heredado es el valor predeterminado en Visual Studio 2017 versión 15.7 y versiones anteriores.

• Para usar el depurador heredado, seleccione Herramientas>Opciones, expanda las opciones Python>Depuración y seleccione la opción Usar el depurador heredado.

Compatibilidad con versiones anteriores de Visual Studio o Python

Visual Studio 2017 versión 15.8 y posteriores usan un depurador basado en ptvsd 4.1 y posteriores. Visual Studio 2019 versión 16.5 y posteriores usan un depurador basado en debugpy. Estas dos versiones del depurador son compatibles con Python 2.7 o Python 3.5 y posteriores.

Si está ejecutando una de estas versiones de Visual Studio, pero usa Python 2.6, 3.1 a 3.4 o IronPython, Visual Studio muestra el error, El depurador no admite este entorno de Python:

Cuando Visual Studio notifica este error de entorno, debe usar el depurador heredado.

Compatibilidad con versiones anteriores de ptvsd

Si está usando una versión anterior de ptvsd en el entorno actual (por ejemplo, una versión 4.0.x anterior de una versión 3.x necesaria para la depuración remota), es posible que Visual Studio muestre un error o una advertencia.

Si el entorno usa ptvsd 3.x, Visual Studio muestra el error, No se pudo cargar el paquete del depurador:

La advertencia El paquete del depurador está obsoleto aparece cuando utiliza una versión anterior a 4.x de ptvsd:

Cuando Visual Studio notifica estos errores de entorno, debe usar el depurador heredado.

Importante

Aunque puede omitir la advertencia en algunas versiones de ptvsd, es posible que Visual Studio no funcione correctamente.

Gestión de la instalación de ptvsd

Siga estos pasos para gestionar la instalación de ptvsd:

1. En la ventana Entornos de Python, vaya a la pestaña Paquetes.

2. Escriba ptvsd en el cuadro de búsqueda y examine la versión de ptvsd instalada:

   

3. Si la versión es anterior a 4.1.1a9 (la versión incluida con Visual Studio), seleccione el símbolo X a la derecha del paquete para desinstalar la versión anterior. Visual Studio usará la versión incluida. (También puede desinstalar desde PowerShell mediante el comando pip uninstall ptvsd).

4. Como alternativa, puede actualizar el paquete de ptvsd a su versión más reciente siguiendo las instrucciones de la sección Solución de problemas de depuración.

Solución de problemas de escenarios de depuración

En los escenarios siguientes se describen otras opciones de solución de problemas para la configuración de depuración.

Actualización de ptvsd para Visual Studio 2019

Si tiene problemas con el depurador en Visual Studio 2019, versión 16.4 y anteriores, actualice primero la versión del depurador de la siguiente manera:

1. En la ventana Entornos de Python, vaya a la pestaña Paquetes.

2. Escriba ptvsd --upgrade en el cuadro de búsqueda y seleccione Ejecutar comando: pip install ptvsd --upgrade -pre. (También puede usar el mismo comando desde PowerShell).

   

   Si los problemas persisten, registre una incidencia en el Repositorio de GitHub de PTVS.

   Nota:

   Para Visual Studio 2019 16.5 y versiones posteriores, debugpy forma parte de la carga de trabajo de Python de Visual Studio y se actualiza junto con Visual Studio.

Habilitación del registro del depurador

En el transcurso de la investigación de un problema del depurador, Microsoft puede pedirle que habilite y recopile registros de depurador que ayudan en el diagnóstico.

Los pasos siguientes habilitan la depuración en la sesión actual de Visual Studio:

1. Abra una ventana de comandos en Visual Studio seleccionando Ver>Otras ventanas>Ventana de comandos.

2. Escriba el comando siguiente:

   DebugAdapterHost.Logging /On /OutputWindow
   

3. Inicie la depuración y recorra los pasos necesarios para reproducir el problema. Durante este tiempo, los registros de depuración aparecen en la ventana Salida bajo Registro del host de adaptador de depuración. Luego puede copiar los registros de esa ventana y pegarlos en una incidencia de GitHub, correo electrónico, etc.

   

4. Si Visual Studio deja de responder o le resulta imposible acceder a la ventana Salida, reinicie Visual Studio, abra una ventana de comandos y escriba el siguiente comando:

   DebugAdapterHost.Logging /On
   

5. Inicie la depuración y reproduzca el problema de nuevo. Los registros del depurador se encuentran en %temp%\DebugAdapterHostLog.txt.

Contenido relacionado

• Depurar en Visual Studio
• Mixed-mode Python/C++ debugging (Depuración en modo mixto Python/C++)
• Symbols for mixed-mode debugging (Símbolos de depuración en modo mixto)