# `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=False, 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.

  When creating a breakpoint, its associated `file name` should be in canonical form. If a `funcname` is defined, a breakpoint `hit` will be counted when the first line of that function is executed. A `conditional` breakpoint always counts a `hit`.

  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:

    - Breakpoint number.

    - Temporary status (del or keep).

    - File/line position.

    - Break condition.

    - Number of times to ignore.

    - Number of times hit.

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

  `Breakpoint` instances have the following attributes:

  `file`

    File name of the `Breakpoint`.

  `line`

    Line number of the `Breakpoint` within `file`.

  `temporary`

    True if a `Breakpoint` at (file, line) is temporary.

  `cond`

    Condition for evaluating a `Breakpoint` at (file, line).

  `funcname`

    Function name that defines whether a `Breakpoint` is hit upon entering the function.

  `enabled`

    True if `Breakpoint` is enabled.

  `bpbynumber`

    Numeric index for a single instance of a `Breakpoint`.

  `bplist`

    Dictionary of `Breakpoint` instances indexed by (`file`, `line`) tuples.

  `ignore`

    Number of times to ignore a `Breakpoint`.

  `hits`

    Count of the number of times a `Breakpoint` has been hit.

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)

    Return canonical form of filename.

    For real file names, the canonical form is an operating-system-dependent, `case-normalized` `absolute path`. A filename with angle brackets, such as `"<stdin>"` generated in interactive mode, is returned unchanged.

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

  `is_skipped_line`(module_name)

    Return True if module_name matches any skip pattern.

  `stop_here`(frame)

    Return True if frame is below the starting frame in the stack.

  `break_here`(frame)

    Return True if there is an effective breakpoint for this line.

    Check whether a line or function breakpoint exists and is in effect. Delete temporary breakpoints based on information from `effective()`.

  `break_anywhere`(frame)

    Return True if any breakpoint exists for frame’s filename.

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

  `user_call`(frame, argument_list)

    Called from `dispatch_call()` if a break might stop inside the called function.

  `user_line`(frame)

    Called from `dispatch_line()` when either `stop_here()` or `break_here()` returns `True`.

  `user_return`(frame, return_value)

    Called from `dispatch_return()` when `stop_here()` returns `True`.

  `user_exception`(frame, exc_info)

    Called from `dispatch_exception()` when `stop_here()` returns `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, lineno=None)

    Stop when the line with the lineno greater than the current one is reached or when returning from current frame.

  `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=False, cond=None, funcname=None)

    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)

    Delete the breakpoints in filename and lineno. If none were set, return an error message.

  `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)

    Delete all breakpoints in filename. If none were set, return an error message.

  `clear_all_breaks`()

    Delete all existing breakpoints. If none were set, return an error message.

  `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)

    Return True if there is a breakpoint for lineno in 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)

    Return a list of (frame, lineno) tuples in a stack trace, and a size.

    The most recently called frame is last in the list. The size is the number of frames below the frame where the debugger was invoked.

  `format_stack_entry`(frame_lineno, lprefix=': ')

    Return a string with information about a stack entry, which is a `(frame, lineno)` tuple. The return string contains:

    - The canonical filename which contains the frame.

    - The function name or `"<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)

  Return True if we should break here, depending on the way the `Breakpoint` b was set.

  If it was set via line number, it checks if `b.line` is the same as the one in frame. If the breakpoint was set via `function name`, we have to check we are in the right frame (the right function) and if we are on its first executable line.

`bdb.``effective`(file, line, frame)

  Return `(active breakpoint, delete temporary flag)` or `(None, None)` as the breakpoint to act upon.

  The active breakpoint is the first entry in `bplist` for the (`file`, `line`) (which must exist) that is `enabled`, for which `checkfuncname()` is True, and that has neither a False `condition` nor positive `ignore` count. The flag, meaning that a temporary breakpoint should be deleted, is False only when the `cond` cannot be evaluated (in which case, `ignore` count is ignored).

  If no such entry exists, then (None, None) is returned.

`bdb.``set_trace`()

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