Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
Visual Studio proporciona una experiencia de depuración completa para Python. En este artículo, explorará cómo adjuntar 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)
Prerrequisitos
Visual Studio instalado con compatibilidad con cargas de trabajo de Python. Para obtener más información, consulte Instalación de 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 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, consulte entornos de Python.
Exploración de la depuración básica
El flujo de trabajo de depuración básico implica la configuración de puntos de interrupción, recorrer el código paso a paso, inspeccionar valores y manejar 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.
Establecimiento del archivo de inicio del proyecto
El archivo de inicio de un proyecto se muestra en negrita en 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.
Especificar el 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 Seleccionar 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.
Establecer puntos de interrupción
Los puntos de interrupción detienen la ejecución del código en un punto marcado para 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 función o clase 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 es 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. Aparece un punto rojo en cada línea que tiene un punto de interrupción establecido.
Para quitar 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.
Establecimiento de condiciones y acciones
Puede personalizar las condiciones en las que se desencadena un punto de interrupción, como la interrupción solo cuando una variable se establece en un determinado valor o intervalo de valores.
Para establecer 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 del reloj o un diamante.
Paso a paso por 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 del Depurador, el menú Depurar, el menú contextual con el botón derecho en el editor de código, y a través de atajos de teclado.
En la tabla siguiente se resumen estos comandos y se proporciona el método abreviado de teclado:
| Get-Help | Método abreviado | Descripción |
|---|---|---|
| Detener | Mayús + F5 | Detenga la sesión de depuración. |
| Reiniciar | Ctrl + Mayús + F5 | Reinicie la sesión de depuración actual. |
| Continuar | F5 | Ejecute el código hasta llegar al siguiente punto de interrupción. |
| Step Into | 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 llamada. |
| Step Over | F10 | Ejecute la siguiente instrucción, incluida la realización de una llamada a una función (ejecutando todo su código) y aplicando cualquier valor devuelto. Este comando permite omitir fácilmente las funciones que no es necesario depurar. |
| Step Out | Mayús+F11 | Ejecute el código hasta el final de la función actual y, a continuación, paso a la instrucción de llamada. Este comando es útil cuando no es necesario 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 permite omitir fácilmente un segmento de código que no es necesario 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+\ | Regrese a la siguiente instrucción para ejecutarla en el código. Este comando le ayuda a localizar el lugar en el código donde se detiene el depurador. |
Inspección y modificación de valores
Al detener la ejecución de código en el depurador, puede inspeccionar y modificar los valores de las 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 utilizando la función DataTips durante la depuración, pase el ratón 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 que están cerca de la instrucción actual. Puede hacer doble clic en la columna de valor o seleccionar y escribir F2 para editar 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 están en el ámbito actual. Puede hacer doble clic en la columna de valor o seleccionar y escribir F2 para editar el valor:
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. Los tipos
str,unicode,bytesybytearrayestán disponibles para su inspección.En el menú desplegable Ver se muestran 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 comilla 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.
Ver excepciones
Si se produce un error en el programa durante la depuración, pero no tiene 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 forma predeterminada, la mayoría de las excepciones se interrumpen cuando no se encuentra 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 aparezca 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 iniciador de Python estándar, sin argumentos de línea de comandos y ninguna otra ruta 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 Propiedadesy luego seleccione la pestaña Depurar.
En las secciones siguientes se describen las propiedades específicas.
Definición del comportamiento de inicio
En la siguiente tabla se enumeran los valores posibles para la propiedad modo de inicio. Use esta propiedad para definir el comportamiento de inicio del depurador.
| Valor | Descripción |
|---|---|
| Iniciador estándar de Python | Use el código de depuración escrito en Python portátil compatible con CPython, IronPython y variantes como Stackless Python. Esta opción proporciona la mejor experiencia para depurar código de Python puro. Cuando te conectas a un proceso de 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 | Ejecute su navegador predeterminado al iniciar el sistema y habilite la depuración de plantillas. Para obtener más información, consulte la sección Depuración de plantillas web. |
| Iniciador web de Django | Implemente un comportamiento idéntico a la propiedad del iniciador web de, pero para un entorno de Django. Use esta opción solo con fines de compatibilidad con versiones anteriores. |
| Iniciador de IronPython (.NET) | Usa el depurador de .NET, que solo funciona con IronPython, pero permite hacer pasos entre cualquier proyecto de lenguaje .NET, incluidos C# y Visual Basic. Este iniciador se usa si se asocia a un proceso de .NET en ejecución que hospeda IronPython. |
Definición del comportamiento de ejecución
En la tabla siguiente se describen las propiedades que puede establecer 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 | Defina los argumentos que se van a agregar al comando que Visual Studio usa para iniciar el script y aparezca después del nombre de archivo del script. El primer elemento que aparece en el valor está disponible para el script como sys.argv[1], el segundo como sys.argv[2], etc. |
| Argumentos del intérprete | Enumere 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 usar E/S no almacenada en búfer. Es probable que los usuarios de IronPython usen este campo para pasar opciones de -X, como -X:Frames o -X:MTA. |
| Ruta del Intérprete | Identifique 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 del formulario <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. |
Trabajar 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.
Abrir la ventana Inmediata
Puede usar la ventana estándar de Visual Studio Inmediato 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 , según se describe en la tabla siguiente.
| Get-Help | 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 |
Cambie el marco actual al identificador de marco especificado. - Requiere un argumento <frame ID>. |
$load |
Cargue los comandos desde el archivo y ejecútelos hasta completarlos. |
$proc |
Muestra el identificador de proceso actual. |
$proc |
Cambie 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 |
Cambie el hilo actual al ID de hilo 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 del depurador estándar, como Procesos, Subprocesos, y Pila de llamadas, no se sincronizan 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 versiones 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 la configuración predeterminada en Visual Studio 2017 versión 15.7 y anteriores.
- Para usar el depurador heredado, seleccione Herramientas>Opciones, expanda las opciones Python>Depuración y seleccione la opción Usar depurador heredado.
Compatibilidad con versiones anteriores de Visual Studio o Python
Visual Studio 2017 versión 15.8 y versiones posteriores usan un depurador basado en ptvsd versión 4.1 y posteriores. Visual Studio 2019 versión 16.5 y versiones posteriores usan un depurador basado en debugpy. Estas dos versiones del depurador son compatibles con Python 2.7 o Python 3.5 y versiones posteriores.
Si ejecuta una de estas versiones de Visual Studio, pero usa Python 2.6, 3.1 a 3.4 o IronPython, Visual Studio muestra el error, Debugger 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 usa una versión anterior de ptvsd en el entorno actual (por ejemplo, una versión anterior de 4.0.x o una versión 3.x necesaria para la depuración remota), Visual Studio podría mostrar un error o una advertencia.
Si el entorno usa ptvsd 3.x, Visual Studio muestra el error paquete Debugger no se pudo cargar:
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 optar por omitir la advertencia de algunas versiones de ptvsd, Es posible que Visual Studio no funcione correctamente.
Administración de la instalación de ptvsd
Siga estos pasos para administrar la instalación de ptvsd:
En la ventana Entornos de Python, vaya a la pestaña Paquetes.
Escriba ptvsd en el cuadro de búsqueda y examine la versión instalada de ptvsd:
Si la versión es inferior a la 4.1.1a9 (la versión agrupada con Visual Studio), seleccione la X a la derecha del paquete para desinstalar la versión anterior. A continuación, Visual Studio usa su versión agrupada. (También puede desinstalar desde PowerShell mediante el comando
pip uninstall ptvsd).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:
En la ventana Entornos de Python, vaya a la pestaña Paquetes.
Escriba ptvsd --upgrade en el cuadro de búsqueda y seleccione Ejecutar comando: pip install ptvsd --upgrade. (También puede usar el mismo comando desde PowerShell).
Si los problemas persisten, abra un problema en el repositorio de GitHub de PTVS.
Nota
Para Visual Studio 2019, versión 16.5 y 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 curso de investigar un problema del depurador, Microsoft puede pedirle que habilite y recopile registros del depurador para ayudar en el diagnóstico.
Los pasos siguientes habilitan la depuración en la sesión actual de Visual Studio:
Para abrir una ventana de comandos en Visual Studio, seleccione Ver>Otras ventanas>Ventana de comandos.
Escriba el siguiente comando:
DebugAdapterHost.Logging /On /OutputWindowInicie 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. Después, puede copiar los registros de esa ventana y pegarlos en un problema de GitHub, correo electrónico, etc.
Si Visual Studio deja de responder o no puede acceder a la ventana Salida, reinicie Visual Studio, abra una ventana de comandos y escriba el siguiente comando:
DebugAdapterHost.Logging /OnInicie 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)