pdb — El Depurador de Python

Código fuente: Lib/unittest/mock.py

El módulo pdb define un depurador de código fuente interactivo para programas Python. Soporta el establecimiento de puntos de ruptura (condicionales) y pasos sencillos a nivel de línea de código fuente, inspección de marcos de pila, listado de código fuente, y evaluación de código Python arbitrario en el contexto de cualquier marco de pila. También soporta depuración post-mortem y puede ser llamado bajo control del programa.

El depurador es extensible – en realidad se define como la clase Pdb. Esto no está actualmente documentado pero se entiende fácilmente leyendo la fuente. La interfaz de extensión usa los módulos bdb y cmd.

El mensaje del depurador es (Pdb). El uso típico para ejecutar un programa bajo el control del depurador es:

>>> import pdb
>>> import mymodule
>>> pdb.run('mymodule.test()')
> <string>(0)?()
(Pdb) continue
> <string>(1)?()
(Pdb) continue
NameError: 'spam'
> <string>(1)?()
(Pdb)

Distinto en la versión 3.3: La finalización de tabulación a través del módulo readline está disponible para comandos y argumentos de comando, por ejemplo. Los nombres globales y locales actuales se ofrecen como argumentos del comando p.

pdb.py también puede ser invocado como un script para depurar otros scripts. Por ejemplo:

python3 -m pdb myscript.py

Cuando se invoca como script, pdb entrará automáticamente en la depuración post-mortem si el programa que se depura sale de forma anormal. Después de la depuración post-mortem (o después de la salida normal del programa), pdb reiniciará el programa. El reinicio automático preserva el estado de pdb (como los puntos de ruptura) y en la mayoría de los casos es más útil que abandonar el depurador al salir del programa.

Nuevo en la versión 3.2: pdb.py ahora acepta una opción -c que ejecuta comandos como si se dieran en un archivo .pdbrc, ver Comandos del depurador.

Nuevo en la versión 3.7: pdb.py ahora acepta una opción -m que ejecuta módulos similares a los que python3 -m hace. Como con un script, el depurador detendrá la ejecución justo antes de la primera línea del módulo.

El uso típico para entrar en el depurador de un programa en ejecución es insertar:

import pdb; pdb.set_trace()

En el lugar donde quieres ingresar en el depurador. Entonces puedes pasar a través del código siguiendo esta declaración, y continuar corriendo sin el depurador usando el comando continue.

Nuevo en la versión 3.7: La breakpoint() incorporada cuando se llama con los valores por defecto, puede ser usado en lugar del import pdb; pdb.set_trace().

El uso típico para inspeccionar un programa que se ha estrellado es:

>>> import pdb
>>> import mymodule
>>> mymodule.test()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "./mymodule.py", line 4, in test
    test2()
  File "./mymodule.py", line 3, in test2
    print(spam)
NameError: spam
>>> pdb.pm()
> ./mymodule.py(3)test2()
-> print(spam)
(Pdb)

El módulo define las siguientes funciones; cada una de ellas entra en el depurador de una manera ligeramente diferente:

pdb.run(statement, globals=None, locals=None)

Ejecutar el statement (dado como una cadena o un objeto de código) bajo el control del depurador. El prompt del depurador aparece antes de que se ejecute cualquier código; puedes establecer puntos de ruptura y escribir continue, o puedes pasar por la declaración usando step o next (todos estos comandos se explican más abajo). Los argumentos opcionales globals y locals especifican el entorno en el que se ejecuta el código; por defecto se utiliza el diccionario del módulo __main__. (Ver la explicación de las funciones incorporadas exec() o eval()).

pdb.runeval(expression, globals=None, locals=None)

Evalúa la expression (dada como una cadena o un objeto de código) bajo el control del depurador. Cuando vuelve runeval(), retorna el valor de la expresión. En caso contrario, esta función es similar a run().

pdb.runcall(function, *args, **kwds)

Llama a la function (un objeto de función o método, no una cadena) con los argumentos dados. Cuando runcall() retorna, retorna lo que sea que la llamada de la función haya retornado. El aviso del depurador aparece tan pronto como se introduce la función.

pdb.set_trace(*, header=None)

Entra en el depurador en el marco de la pila de llamadas. Esto es útil para codificar duramente un punto de interrupción en un punto dado de un programa, incluso si el código no se depura de otra manera (por ejemplo, cuando una afirmación falla). Si se da, se imprime el header en la consola justo antes de que comience la depuración.

Distinto en la versión 3.7: El argumento de la palabra clave header.

pdb.post_mortem(traceback=None)

Ingresa a la depuración post-mortem del objeto traceback dado. Si no se da un traceback, utiliza el de la excepción que se está manejando actualmente (una excepción debe ser manejada si se va a utilizar el predeterminado).

pdb.pm()

Ingresa a la depuración post-mortem de la traza encontrada en sys.last_traceback.

Las funciones run* y set_trace() son alias para instanciar la clase Pdb y llamar al método del mismo nombre. Si quieres acceder a más funciones, tienes que hacerlo tú mismo:

class pdb.Pdb(completekey='tab', stdin=None, stdout=None, skip=None, nosigint=False, readrc=True)

Pdb es la clase de depuración.

Los argumentos completekey, stdin y stdout se pasan a la subyacente cmd.Cmd class; ver la descripción allí.

El argumento skip, si se da, debe ser un iterable de los patrones de nombre de los módulos de estilo global. El depurador no entrará en marcos que se originen en un módulo que coincida con uno de estos patrones. 1

Por defecto, Pdb establece un manejador para la señal de SIGINT (que se envía cuando el usuario presiona Ctrl-C en la consola) cuando da un comando de continue. Esto te permite entrar en el depurador de nuevo presionando Ctrl-C. Si quieres que Pdb no toque el manejador de SIGINT, pon nosigint en true.

El argumento * readrc * por defecto es verdadero y controla si Pdb cargará archivos .pdbrc desde el sistema de archivos.

Ejemplo de llamada para permitir el rastreo con skip:

import pdb; pdb.Pdb(skip=['django.*']).set_trace()

Levanta una auditing event pdb.Pdb sin argumentos.

Nuevo en la versión 3.1: El argumento skip.

Nuevo en la versión 3.2: El argumento del nosigint. Anteriormente, un manejador SIGINT nunca fue establecido por Pdb.

Distinto en la versión 3.6: El argumento readrc.

run(statement, globals=None, locals=None)
runeval(expression, globals=None, locals=None)
runcall(function, *args, **kwds)
set_trace()

Véase la documentación para las funciones explicadas anteriormente.

Comandos del depurador

Los comandos reconocidos por el depurador se enumeran a continuación. La mayoría de los comandos pueden abreviarse a una o dos letras como se indica; por ejemplo, h(elp) significa que se puede usar h o help para introducir el comando de ayuda (pero no he o hel, ni H o Help o HELP). Los argumentos de los comandos deben estar separados por espacios en blanco (espacios o tabulaciones). Los argumentos opcionales están encerrados entre corchetes ([]) en la sintaxis del comando; los corchetes no deben escribirse. Las alternativas en la sintaxis de los comandos están separadas por una barra vertical (|).

Introducir una línea en blanco repite el último comando introducido. Excepción: si el último comando fue un list comando, las siguientes 11 líneas están listadas.

Se supone que los comandos que el depurador no reconoce son declaraciones en Python y se ejecutan en el contexto del programa que se está depurando. Las declaraciones en Python también pueden ser precedidas por un signo de exclamación (!). Esta es una manera poderosa de inspeccionar el programa que se está depurando; incluso es posible cambiar una variable o llamar a una función. Cuando se produce una excepción en una sentencia de este tipo, se imprime el nombre de la excepción pero no se cambia el estado del depurador.

El depurador soporta aliases. Los alias pueden tener parámetros que permiten un cierto nivel de adaptabilidad al contexto que se está examinando.

Se pueden introducir múltiples comandos en una sola línea, separados por ;;. (No se usa un solo ; ya que es el separador de múltiples comandos en una línea que se pasa al analizador de Python). No se aplica ninguna inteligencia para separar los comandos; la entrada se divide en el primer par ;;, incluso si está en medio de una cadena citada.

Si un archivo .pdbrc existe en el directorio principal del usuario o en el directorio actual, se lee y se ejecuta como si se hubiera escrito en el prompt del depurador. Esto es particularmente útil para los alias. Si ambos archivos existen, el del directorio principal se lee primero y los alias definidos allí pueden ser anulados por el archivo local.

Distinto en la versión 3.2: .pdbrc puede ahora contener comandos que continúan depurando, como continue o next. Anteriormente, estos comandos no tenían ningún efecto.

h(elp) [command]

Sin argumento, imprime la lista de comandos disponibles. Con un command como argumento, imprime la ayuda sobre ese comando. help pdb muestra la documentación completa (el docstring del módulo pdb). Como el argumento command debe ser un identificador, hay que introducir help exec para obtener ayuda sobre el comando !.

w(here)

Imprime un rastro de la pila (stack trace), con el marco más reciente en la parte inferior. Una flecha indica el marco actual, que determina el contexto de la mayoría de los comandos.

d(own) [count]

Mueve los niveles del marco actual count (por defecto uno) hacia abajo en el trazado de la pila (stack trace) (a un marco más nuevo).

u(p) [count]

Mueve el marco actual count (por defecto uno) niveles hacia arriba en el trazado de la pila (stack trace) (a un marco más antiguo).

b(reak) [([filename:]lineno | function) [, condition]]

Con un argumento lineno, establece una ruptura allí en el archivo actual. Con un argumento function, establece una ruptura en la primera declaración ejecutable dentro de esa función. El número de línea puede ir precedido de un nombre de archivo y dos puntos, para especificar un punto de interrupción en otro archivo (probablemente uno que aún no se haya cargado). El archivo se busca en sys.path. Observe que a cada punto de interrupción se le asigna un número al que se refieren todos los demás comandos de puntos de interrupción.

Si un segundo argumento está presente, es una expresión que debe ser evaluada como verdadera antes de que el punto de ruptura sea honrado.

Sin argumento, enumere todas las interrupciones, incluyendo para cada punto de interrupción, el número de veces que se ha alcanzado ese punto de interrupción, el conteo de ignorancia actual y la condición asociada, si la hay.

tbreak [([filename:]lineno | function) [, condition]]

Punto de interrupción temporal, que se elimina automáticamente cuando se ejecuta por primera vez. Los argumentos son los mismos que para break.

cl(ear) [filename:lineno | bpnumber [bpnumber ...]]

Con el argumento filename:lineno, despeja todos los puntos de interrupción en esta línea. Con una lista de números de puntos de interrupción separados por espacios, despeja esos puntos de interrupción. Sin el argumento, despeja todos los puntos de interrupción (pero primero pide confirmación).

disable [bpnumber [bpnumber ...]]

Deshabilitar los puntos de ruptura interrupción como una lista de números de puntos de ruptura separados por espacios. Desactivar un punto de interrupción significa que no puede hacer que el programa detenga la ejecución, pero a diferencia de borrar un punto de interrupción, permanece en la lista de puntos de interrupción y puede ser (re)activado.

enable [bpnumber [bpnumber ...]]

Habilitar los puntos de interrupción especificados.

ignore bpnumber [count]

Establece el conteo de ignorar el número de punto de interrupción dado. Si se omite el recuento, el recuento de ignorar se establece en 0. Un punto de interrupción se activa cuando el recuento de ignorar es cero. Cuando no es cero, el conteo se decrementa cada vez que se alcanza el punto de ruptura y el punto de ruptura no se desactiva y cualquier condición asociada se evalúa como verdadera.

condition bpnumber [condition]

Establece una nueva condition para el punto de interrupción, una expresión que debe evaluarse como verdadera antes de que el punto de ruptura sea honrado. Si la condición está ausente, se elimina cualquier condición existente, es decir, el punto de ruptura se hace incondicional.

commands [bpnumber]

Especifique una lista de comandos para el número del punto de interrupción bpnumber. Los comandos mismos aparecen en las siguientes líneas. Escriba una línea que contenga sólo end para terminar los comandos. Un ejemplo:

(Pdb) commands 1
(com) p some_variable
(com) end
(Pdb)

Para eliminar todos los comandos de un punto de interrupción, escribe commands y sigue inmediatamente con end , es decir, no des órdenes.

Sin el argumento bpnumber, commands se refiere al último punto de interrupción establecido.

Puede utilizar los comandos de punto de interrupción para iniciar el programa de nuevo. Simplemente usa el comando continue, o step, o cualquier otro comando que reanude la ejecución.

Al especificar cualquier comando que reanude la ejecución (actualmente continue, step, next, return, jump, quit y sus abreviaturas) se termina la lista de comandos (como si ese comando fuera inmediatamente seguido de end.) Esto se debe a que cada vez que se reanuda la ejecución (incluso con un simple siguiente o paso), puede encontrarse con otro punto de interrupción, que podría tener su propia lista de comandos, lo que conduce a ambigüedades sobre qué lista ejecutar.

Si utiliza el comando “silent” en la lista de comandos, no se imprime el mensaje habitual sobre la parada en un punto de interrupción. Esto puede ser deseable para los puntos de interrupción que deben imprimir un mensaje específico y luego continuar. Si ninguno de los otros comandos imprime nada, no se ve ninguna señal de que se haya alcanzado el punto de interrupción.

s(tep)

Ejecutar la línea actual, detenerse en la primera ocasión posible (ya sea en una función que se llame o en la siguiente línea de la función actual).

n(ext)

Continúe la ejecución hasta que se alcance la siguiente línea de la función actual o vuelva. (La diferencia entre next y step es que step se detiene dentro de una función llamada, mientras que next ejecuta las funciones llamadas a (casi) toda velocidad, deteniéndose sólo en la siguiente línea de la función actual).

unt(il) [lineno]

Sin argumento, continúe la ejecución hasta que se alcance la línea con un número mayor que el actual.

Con un número de línea, continúe la ejecución hasta que se alcance una línea con un número mayor o igual a ese. En ambos casos, también se detiene cuando vuelve la trama actual.

Distinto en la versión 3.2: Permita dar un número de línea explícito.

r(eturn)

Continúe la ejecución hasta que vuelva la función actual.

c(ont(inue))

Continúa la ejecución, sólo se detiene cuando se encuentra un punto de ruptura.

j(ump) lineno

Establezca la siguiente línea que será ejecutada. Sólo disponible en el marco de más bajo. Esto te permite saltar hacia atrás y ejecutar el código de nuevo, o saltar hacia adelante para saltar el código que no quieres ejecutar.

Cabe señalar que no todos los saltos están permitidos – por ejemplo, no es posible saltar en medio de un bucle for o fuera de una cláusula finally.

l(ist) [first[, last]]

Enumere el código fuente del archivo actual. Sin argumentos, enumere 11 líneas alrededor de la línea actual o continúe la lista anterior. Con . como argumento, enumere 11 líneas alrededor de la línea actual. Con un argumento, enumere 11 líneas alrededor de esa línea. Con dos argumentos, enumere el rango dado; si el segundo argumento es menor que el primero, se interpreta como un conteo.

La línea actual en el cuadro actual se indica con ->. Si se está depurando una excepción, la línea donde la excepción fue originalmente planteada o propagada se indica con >>, si difiere de la línea actual.

Nuevo en la versión 3.2: El marcador >> .

ll | longlist

Enumere todos los códigos fuente de la función o marco actual. Las líneas interesantes están marcadas como list.

Nuevo en la versión 3.2.

a(rgs)

Imprime la lista de argumentos de la función actual.

p expression

Evalúa la expression en el contexto actual e imprime su valor.

Nota

print() también se puede usar, pero no es un comando de depuración — esto ejecuta la función Python print().

pp expression

Como el comando p, excepto que el valor de la expresión se imprime bastante usando el módulo pprint.

whatis expression

Imprime el tipo de la expression.

source expression

Intenta obtener el código fuente del objeto dado y mostrarlo.

Nuevo en la versión 3.2.

display [expression]

Muestra el valor de la expresión si ha cambiado, cada vez que se detenga la ejecución en el marco actual.

Sin expresión, enumere todas las expresiones de visualización para el cuadro actual.

Nuevo en la versión 3.2.

undisplay [expression]

No muestren más la expresión en el cuadro actual. Sin la expresión, borre todas las expresiones de la pantalla para el marco actual.

Nuevo en la versión 3.2.

interact

Inicie un intérprete interactivo (usando el módulo code) cuyo espacio de nombres global contiene todos los nombres (globales y locales) que se encuentran en el ámbito actual.

Nuevo en la versión 3.2.

alias [name [command]]

Crear un alias llamado name que ejecute el command. El comando no debe estar entre comillas. Los parámetros reemplazables pueden ser indicados por %1, %2, y así sucesivamente, mientras que %* es reemplazado por todos los parámetros. Si no se da ningún comando, se muestra el alias actual de name. Si no se dan argumentos, se muestran todos los alias.

Los alias pueden anidarse y pueden contener cualquier cosa que se pueda teclear legalmente en el prompt de pdb. Tenga en cuenta que los comandos internos de pdb pueden ser anulados por los alias. Dicho comando se oculta hasta que se elimina el alias. El alias se aplica de forma recursiva a la primera palabra de la línea de comandos; todas las demás palabras de la línea se dejan en paz.

Como ejemplo, aquí hay dos alias útiles (especialmente cuando se colocan en el archivo .pdbrc):

# Print instance variables (usage "pi classInst")
alias pi for k in %1.__dict__.keys(): print("%1.",k,"=",%1.__dict__[k])
# Print instance variables in self
alias ps pi self
unalias name

Elimine el alias especificado.

! statement

Ejecute (una línea) statement en el contexto del marco de la pila actual. El signo de exclamación puede ser omitido a menos que la primera palabra de la declaración se parezca a un comando de depuración. Para establecer una variable global, puede anteponer al comando de asignación una declaración global en la misma línea, por ejemplo:

(Pdb) global list_options; list_options = ['-l']
(Pdb)
run [args ...]
restart [args ...]

Reinicie el programa Python depurado. Si se suministra un argumento, se divide con shlex y el resultado se utiliza como el nuevo sys.argv. Se conservan el historial, los puntos de interrupción, las acciones y las opciones del depurador. restart es un alias de run.

q(uit)

Salga del depurador. El programa que se está ejecutando fue abortado.

debug code

Introduce un depurador recursivo que pasa por el argumento del código (que es una expresión o declaración arbitraria que debe ejecutarse en el entorno actual).

retval

Print the return value for the last return of a function.

Notas de pie de página

1

Si se considera que un marco se origina en un determinado módulo se determina por el __name__ en el marcos globales.