"bdb" --- Framework de depuración
*********************************

**Source code:** Lib/bdb.py

======================================================================

El módulo "bdb" maneja las funciones básicas del depurador, como
establecer puntos de interrupción o gestionar la ejecución a través
del mismo.

La siguiente excepción es definida:

exception bdb.BdbQuit

   Excepción lanzada por la clase "Bdb" al salir del depurador.

El módulo "bdb" también define dos clases:

class bdb.Breakpoint(self, file, line, temporary=0, cond=None, funcname=None)

   Esta clase implementa puntos de interrupción temporales,
   permitiendo ignorar recuentos, desactivar y (re-)activar puntos de
   interrupción y definir condiciones de interrupción para los mismos.

   Los puntos de interrupción se indexan numéricamente mediante una
   lista llamada "bpbynumber" y por pares "(archivo, linea)" mediante
   "bplist". En el primer caso se apunta a una única instancia de
   "Breakpoint". En el segundo caso se apunta a una lista de tales
   instancias, ya que puede haber más de un punto de interrupción por
   línea.

   Al crear un punto de interrupción, el nombre del archivo asociado
   debe estar en su forma canónica. Si se define un nombre de función
   *funcname*, se contará el punto de interrupción cuando se ejecute
   la primera línea de esa función. Los puntos de interrupción
   condicionales siempre cuentan los alcances.

   Las instancias de la clase "Breakpoint" tienen los siguientes
   métodos:

   deleteMe()

      Elimina el punto de interrupción de la lista asociada a un
      archivo/línea. Si es el último punto de interrupción en esa
      posición, también borra la entrada correspondiente del
      archivo/línea correspondiente.

   enable()

      Marca el punto de interrupción como habilitado.

   disable()

      Marca el punto de interrupción como deshabilitado.

   bpformat()

      Retorna una cadena de caracteres que contiene toda la
      información sobre el punto de interrupción, apropiadamente
      formateada:

      * El número del punto de interrupción.

      * Si es temporal o no.

      * Su archivo, la posición de la línea.

      * La condición que causa la interrupción.

      * Si debe ignorarse las próximas N veces.

      * El recuento de alcances del punto de interrupción.

      Nuevo en la versión 3.2.

   bpprint(out=None)

      Imprime la salida de "bpformat()" en el archivo *out*, o en la
      salida estándar si es "None".

class bdb.Bdb(skip=None)

   La clase "Bdb" actúa como clase base del depurador genérico de
   Python.

   Esta clase se encarga de los detalles de la funcionalidad de
   seguimiento; una clase derivada debería encargarse de implementar
   la interacción con el usuario. Un ejemplo es la clase de depuración
   estándar ("pdb.Pdb").

   El argumento *skip*, si se proporciona, debe ser un iterable con
   patrones de nombre de archivo, al estilo del módulo glob. El
   depurador no entrará en aquellos marcos de ejecución que se
   originen en un módulo que coincida con uno de estos patrones. Para
   determinar si un marco de ejecución se origina en un módulo
   determinado, se hace uso de "__name__" en las variables globales
   del marco de ejecución dado.

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

   Los siguientes métodos de la clase "Bdb" normalmente no necesitan
   ser redefinidos.

   canonic(filename)

      Método auxiliar para obtener el nombre del archivo en su forma
      canónica, es decir, como una ruta absoluta normalizada entre
      mayúsculas y minúsculas (en sistemas de archivos que no
      distinguen entre ambas) y despojada de los corchetes angulares
      circundantes.

   reset()

      Establece los atributos "botframe", "stopframe", "returnframe" y
      "quitting" con valores preparados para comenzar la depuración.

   trace_dispatch(frame, event, arg)

      Esta función se instala como función de seguimiento de los
      marcos de ejecución depurados. Su valor de retorno es la nueva
      función de seguimiento a usar (en la mayoría de los casos, ella
      misma).

      La implementación predeterminada decide cómo despachar un marco
      de ejecución, dependiendo del tipo de evento (pasado como una
      cadena) que está a punto de ejecutarse. *event* puede tomar uno
      de los siguientes valores:

      * ""line"": Se va a ejecutar una nueva línea de código.

      * ""call"": Está a punto de llamarse a una función o se ha
        entrado en otro bloque de código.

      * ""return"": Una función u otro bloque de código está a punto
        de retornar.

      * ""exception"": Ha ocurrido una excepción.

      * ""c_call"": Una función de C está a punto de llamarse .

      * ""c_return"": Una función de C ha retornado.

      * ""c_exception"": Una función de C ha lanzado una excepción.

      Para los eventos de Python, son llamadas funciones
      especializadas (ver más abajo). En cambio, para los eventos de C
      no se realiza ninguna acción.

      El parámetro *arg* depende del evento previo.

      Consulta la documentación de "sys.settrace()" para obtener más
      información sobre la función de seguimiento. Para obtener más
      información sobre los objetos código y los objetos marco
      consulte Jerarquía de tipos estándar.

   dispatch_line(frame)

      Si el depurador tiene que detenerse en la línea actual, invoca
      el método "user_line()" (que debe ser redefinido en las
      subclases). Genera una excepción "BdbQuit" si se establece el
      flag "Bdb.quitting" (que se puede establecer mediante
      "user_line()"). Retorna una referencia al método
      "trace_dispatch()" para realizar un seguimiento adicional en ese
      ámbito.

   dispatch_call(frame, arg)

      Si el depurador tiene que detenerse en esta llamada de función,
      invoca el método "user_call()" (que debe ser redefinido en las
      subclases). Lanza una excepción "BdbQuit" si se establece el
      flag "Bdb.quitting" (que se puede establecer mediante
      "user_call()"). Retorna una referencia al método
      "trace_dispatch()" para realizar un seguimiento adicional en ese
      ámbito.

   dispatch_return(frame, arg)

      Si el depurador tiene que detenerse en el retorno de esta
      función, invoca el método "user_return()" (que debe ser
      redefinido en las subclases). Lanza una excepción "BdbQuit" si
      se establece el flag "Bdb.quitting" (que se puede establecer
      mediante "user_return()"). Retorna una referencia al método
      "trace_dispatch()" para realizar un seguimiento adicional en ese
      ámbito.

   dispatch_exception(frame, arg)

      Si el depurador tiene que detenerse en esta excepción, invoca el
      método "user_exception()" (que debe ser redefinido en las
      subclases). Lanza una excepción "BdbQuit" si se establece el
      flag "Bdb.quitting" (que se puede establecer mediante
      "user_exception()"). Retorna una referencia al método
      "trace_dispatch()" para realizar un seguimiento adicional en ese
      ámbito.

   Las clases derivadas normalmente no necesitan redefinir los
   siguientes métodos, pero pueden hacerlo si necesitan redefinir la
   definición de parada y los puntos de interrupción.

   stop_here(frame)

      Este método comprueba si el *frame* está en cualquier posición
      debajo de "botframe" en la pila de llamadas. "botframe" es el
      marco de ejecución en el que comenzó la depuración.

   break_here(frame)

      Este método comprueba si hay un punto de interrupción en el
      nombre de archivo y la línea pertenecientes a *frame* o, al
      menos, en la función actual. Si el punto de interrupción es
      temporal, este método lo elimina.

   break_anywhere(frame)

      Este método comprueba si hay un punto de interrupción en el
      nombre de archivo del marco de ejecución actual.

   Las clases derivadas deben redefinir estos métodos para adquirir el
   control sobre las operaciones de depuración.

   user_call(frame, argument_list)

      Este método se llama desde "dispatch_call()" cuando existe la
      posibilidad de que sea necesaria una interrupción en cualquier
      lugar dentro de la función llamada.

   user_line(frame)

      Este método se llama desde "dispatch_line()" cuando
      "stop_here()" o "break_here()" generan "True".

   user_return(frame, return_value)

      Este método se llama desde "dispatch_return()" cuando
      "stop_here()" genera "True".

   user_exception(frame, exc_info)

      Este método se llama desde "dispatch_exception()" cuando
      "stop_here()" genera "True".

   do_clear(arg)

      Maneja cómo un punto de interrupción debe ser eliminado cuando
      es temporal.

      Este método debe ser implementado por las clases derivadas.

   Las clases derivadas y los clientes pueden llamar a los siguientes
   métodos para influir en el estado de transición.

   set_step()

      Se detiene después de una línea de código.

   set_next(frame)

      Se detiene en la siguiente línea del marco de ejecución dado o
      en la de uno inferior.

   set_return(frame)

      Se detiene cuando se retorna desde el marco de ejecución dado.

   set_until(frame)

      Se detiene cuando se alcanza un número de línea superior al de
      la línea actual o se retorna desde el marco de ejecución actual.

   set_trace([frame])

      Inicia la depuración desde el marco de ejecución *frame*. Si
      *frame* no se especifica, la depuración se inicia desde el marco
      de ejecución que produce la llamada.

   set_continue()

      Se detiene solo en los puntos de interrupción o cuando haya
      terminado. Si no hay puntos de interrupción, se configura la
      función de seguimiento del sistema en "None".

   set_quit()

      Establece el atributo "quitting" en "True". Esto lanza una
      excepción "BdbQuit" en la siguiente llamada a uno de los métodos
      "dispatch_*()" que tenga lugar.

   Las clases derivadas y los clientes pueden llamar a los siguientes
   métodos para manipular los puntos de interrupción. Estos métodos
   retornan una cadena de caracteres que contiene un mensaje de error
   si algo fue mal, o "None" si todo fue correctamente.

   set_break(filename, lineno, temporary=0, cond, funcname)

      Establece un nuevo punto de interrupción. Si la línea en la
      posición *lineno* no existe en el archivo con nombre *filename*
      pasado como argumento, se retorna un mensaje de error.
      *filename* debe estar en su forma canónica, tal como se describe
      en el método "canonic()".

   clear_break(filename, lineno)

      Elimina el punto de interrupción en el archivo *filename* y
      número de linea *lineno*. Si no se ha establecido ninguno, se
      retorna un mensaje de error.

   clear_bpbynumber(arg)

      Elimina el punto de interrupción que tiene el índice *arg* en
      "Breakpoint.bpbynumber". Si *arg* no es un valor numérico o es
      un indice fuera de rango, se retorna un mensaje de error.

   clear_all_file_breaks(filename)

      Elimina todos los puntos de interrupción en el archivo
      *filename*. Si no se ha establecido ninguno, se retorna un
      mensaje de error.

   clear_all_breaks()

      Elimina todos los puntos de interrupción que existen.

   get_bpbynumber(arg)

      Retorna un punto de interrupción especificado por el número
      dado. Si *arg* es una cadena de caracteres, será convertida en
      un número. Si *arg* es una cadena no numérica, o el punto de
      interrupción dado nunca existió o ya ha sido eliminado, se lanza
      una excepción "ValueError".

      Nuevo en la versión 3.2.

   get_break(filename, lineno)

      Comprueba si hay un punto de interrupción en la linea número
      *lineno* del archivo *filename*.

   get_breaks(filename, lineno)

      Retorna todos los puntos de interrupción en la linea número
      *lineno* del archivo *filename*, o una lista vacía si no se ha
      establecido ninguno.

   get_file_breaks(filename)

      Retorna todos los puntos de interrupción en el archivo
      *filename*, o una lista vacía si no hay ninguno establecido.

   get_all_breaks()

      Retorna todos los puntos de interrupción establecidos.

   Las clases derivadas y clientes pueden llamar los siguientes
   métodos para obtener una estructura de datos que representa un
   seguimiento de pila.

   get_stack(f, t)

      Obtiene una lista de registros para un marco de ejecución y
      todos los marcos de ejecución superiores (que han ocasionado la
      llamadas previas) e inferiores, además del tamaño de la parte
      superior.

   format_stack_entry(frame_lineno, lprefix=': ')

      Retorna una cadena con información sobre una entrada de pila,
      identificada por una tupla de la forma "(cuadro de ejecución,
      número de línea)":

      * La forma canónica del nombre del archivo que contiene el marco
        de ejecución.

      * El nombre de la función o ""<lambda>"".

      * Los argumentos de entrada.

      * El valor de retorno.

      * La linea de código (si existe).

   Los dos métodos descritos a continuación pueden ser llamados por
   los clientes para usar un depurador que se encargue de depurar un
   *statement*, proporcionado como una cadena de caracteres.

   run(cmd, globals=None, locals=None)

      Depura una sentencia ejecutada a través de la función "exec()".
      *globals* por defecto es "__main __.__ dict__", mientras que
      *locals* es *globals* por defecto.

   runeval(expr, globals=None, locals=None)

      Depura una expresión ejecutada mediante la función "eval()".
      *globals* y *locals* tienen el mismo significado que en "run()".

   runctx(cmd, globals, locals)

      Definido solo por compatibilidad con versiones anteriores. Llama
      al método "run()".

   runcall(func, *args, **kwds)

      Depura una única llamada a función y retorna su resultado.

Por último, el módulo también define las siguientes funciones:

bdb.checkfuncname(b, frame)

   Comprueba si se debería interrumpir la ejecución en éste punto,
   dependiendo de la forma en que se estableció el punto de
   interrupción *b*.

   Si se estableció usando el número de línea, verifica si "b.line" es
   el mismo que el del marco de ejecución que también se pasó como
   argumento. Si el punto de interrupción se estableció mediante el
   nombre de la función, tenemos que comprobar que estamos en el
   cuadro de ejecución correcto (la función correcta) y si estamos en
   su primera línea ejecutable.

bdb.effective(file, line, frame)

   Determina si hay un punto de interrupción efectivo (activo) en esta
   línea de código. Retorna una tupla con el punto de interrupción y
   un valor booleano que indica si es correcto eliminar un punto de
   interrupción temporal. Retorna "(None, None)" si no hay un punto de
   interrupción coincidente.

bdb.set_trace()

   Inicia la depuración usando una instancia de "Bdb", partiendo desde
   el marco de ejecución que realiza la llamada.
