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

The typical usage to break into the debugger is to insert:

   import pdb; pdb.set_trace()

at the location you want to break into the debugger, and then run the
program. You can then step through the code following this statement,
and continue running without the debugger using the "continue"
command.

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.

Multiple commands may be entered on a single line, separated by ";;".
(A single ";" is not used as it is the separator for multiple commands
in a line that is passed to the Python parser.)  No intelligence is
applied to separating the commands; the input is split at the first
";;" pair, even if it is in the middle of a quoted string. A
workaround for strings with double semicolons is to use implicit
string concatenation "';'';'" or "";"";"".

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

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

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

   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.
