# `bdb` — Framework do depurador

Código-fonte: Lib/bdb.py

O módulo `bdb` lida com funções básicas do depurador, como definir pontos de interrupção ou gerenciar a execução por meio do depurador.

A seguinte exceção é definida:

exception bdb.BdbQuit

  Exceção levantada pela classe `Bdb` para sair do depurador.

O módulo `bdb` também define duas classes:

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

  Esta classe implementa pontos de interrupção temporários, contagens de ignorar, desativação e (re)ativação, além de condicionais.

  Os pontos de interrupção são indexados por número por meio de uma lista chamada `bpbynumber` e por pares `(file, line)` por meio de `bplist`. O primeiro aponta para uma única instância da classe `Breakpoint`. O segundo aponta para uma lista dessas instâncias, já que pode haver mais de um ponto de interrupção por linha.

  Ao criar um ponto de interrupção, seu `nome do arquivo` associado deve estar no formato canônico. Se um `funcname` for definido, um ponto de interrupção `atingido` será contado quando a primeira linha dessa função for executada. Um ponto de interrupção `condicional` sempre conta um `atingido`.

  As instâncias de `Breakpoint` têm os seguintes métodos:

  deleteMe()

    Exclui o ponto de interrupção da lista associada a um arquivo/linha. Se for o último ponto de interrupção nessa posição, ele também excluirá a entrada do arquivo/linha.

  enable()

    Marca o ponto de interrupção como ativado.

  disable()

    Marca o ponto de interrupção como desativado.

  bpformat()

    Retorna uma string com todas as informações sobre o ponto de interrupção, formatadas de maneira clara:

    - Número do ponto de interrupção.

    - Status temporário (del ou keep).

    - Posição do arquivo/linha.

    - Condição de interrupção.

    - Número de vezes para ignorar.

    - Número de vezes atingido.

    Adicionado na versão 3.2.

  bpprint(out=None)

    Exibe a saída de `bpformat()` no arquivo out ou, se for `None`, na saída padrão.

  Instâncias `Breakpoint` possuem os seguintes atributos:

  file

    Nome do arquivo do `Breakpoint`.

  line

    Número da linha do `Breakpoint` dentro de `file`.

  temporary

    `True` se um `Breakpoint` em (file, line) for temporário.

  cond

    Condição para avaliar um `Breakpoint` em (file, line).

  funcname

    Nome da função que define se um `Breakpoint` é atingido ao entrar na função.

  enabled

    `True` se `Breakpoint` estiver ativado.

  bpbynumber

    Índice numérico de uma única instância de `Breakpoint`.

  bplist

    Dicionário de instâncias de `Breakpoint` indexadas por tuplas (`file`, `line`).

  ignore

    Número de vezes para ignorar o `Breakpoint`.

  hits

    Contagem do número de vezes que um `Breakpoint` foi atingido.

class bdb.Bdb(skip=None)

  A `Bdb` atua como uma classe base genérica de depurador em Python.

  Esta classe cuida dos detalhes do mecanismo de rastreamento; uma classe derivada deve implementar a interação com o usuário. A classe de depuração padrão (`pdb.Pdb`) é um exemplo.

  O argumento skip, se fornecido, deve ser um iterável de padrões de nomes de módulos no estilo glob. O depurador não entrará em frames que se originam em um módulo que corresponda a um desses padrões. Se um frame é considerado como originado em determinado módulo é determinado pelo valor de `__name__` nos globals do frame.

  Alterado na versão 3.1: Adicionado o parâmetro skip.

  Os seguintes métodos de `Bdb` normalmente não precisam ser substituídos.

  canonic(filename)

    Retorna a forma canônica de filename.

    Para nomes de arquivos reais, a forma canônica é um `caminho absoluto`, `normalizado para distinguir maiúsculas e minúsculas`, dependente do sistema operacional. Um filename com colchetes angulares, como `"<stdin>"` gerado no modo interativo, é retornado sem alterações.

  reset()

    Define os atributos `botframe`, `stopframe`, `returnframe` e `quitting` com valores prontos para iniciar a depuração.

  trace_dispatch(frame, event, arg)

    Esta função é instalada como a função de rastreamento dos frames depurados. Seu valor de retorno é a nova função de rastreamento (na maioria dos casos, ela própria).

    A implementação padrão decide como despachar um frame, dependendo do tipo de evento (passado como string) que está prestes a ser executado. event pode ser um dos seguintes:

    - `"line"`: Uma nova linha de código será executada.

    - `"call"`: Um função está prestes a ser chamada, ou outro bloco de código foi inserido.

    - `"retorno"`: Um função ou outro bloco de código está prestes a retornar.

    - `"exception"`: Ocorreu uma exceção.

    - `"c_call"`: Uma função C está prestes a ser chamada.

    - `"c_return"`: Uma função C retornou.

    - `"c_exception"`: Uma função C levantou uma exceção.

    Para os eventos Python, são chamadas função especializadas (consulte abaixo). Para os eventos de C, nenhuma ação é tomada.

    O parâmetro arg depende do evento anterior.

    Consulte a documentação de `sys.settrace()` para mais informações sobre a função de rastreamento. Para mais informações sobre objetos de código e de frame, consulte A hierarquia de tipos padrão.

  dispatch_line(frame)

    Se o depurador deve parar na linha atual, invoca o método `user_line()` (que deve ser substituído em subclasses). Levanta a exceção `BdbQuit` se o sinalizador `quitting` estiver definido (ele pode ser definido a partir de `user_line()`). Retorna uma referência ao método `trace_dispatch()` para continuar o rastreamento nesse escopo.

  dispatch_call(frame, arg)

    Se o depurador deve parar nesta chamada de função, invoca o método `user_call()` (que deve ser substituído em subclasses). Levanta a exceção `BdbQuit` se o sinalizador `quitting` estiver definido (ele pode ser definido a partir de `user_call()`). Retorna uma referência ao método `trace_dispatch()` para continuar o rastreamento nesse escopo.

  dispatch_return(frame, arg)

    Se o depurador deve parar no retorno desta função, invoca o método `user_return()` (que deve ser substituído em subclasses). Levanta a exceção `BdbQuit` se o sinalizador `quitting` estiver definido (ele pode ser definido a partir de `user_return()`). Retorna uma referência ao método `trace_dispatch()` para continuar o rastreamento nesse escopo.

  dispatch_exception(frame, arg)

    Se o depurador deve parar nesta exceção, invoca o método `user_exception()` (que deve ser substituído em subclasses). Levanta a exceção `BdbQuit` se o sinalizador `quitting` estiver definido (ele pode ser definido a partir de `user_exception()`). Retorna uma referência ao método `trace_dispatch()` para continuar o rastreamento nesse escopo.

  Normalmente, as classes derivadas não substituem o seguinte métodos, mas podem fazê-lo se quiserem redefinir a definição de parada e de pontos de interrupção.

  is_skipped_module(module_name)

    Retorna `True` se module_name corresponder a algum padrão de skip.

  stop_here(frame)

    Retorna `True` se frame estiver abaixo do frame inicial na pilha.

  break_here(frame)

    Retorna `True` se houver um ponto de interrupção efetivo para essa linha.

    Verifica se uma linha ou função ponto de interrupção existe e está em vigor. Exclua os pontos de interrupção temporários com base nas informações de `effective()`.

  break_anywhere(frame)

    Retorna `True` se existir algum ponto de interrupção para o nome de arquivo de frame’s.

  As classes derivadas devem substituir esses métodos para obter controle sobre a operação da depurador.

  user_call(frame, argument_list)

    Chamado a partir de `dispatch_call()` se um ponto de interrupção puder parar dentro da função chamada.

    argument_list não é mais usado e sempre será `None`. O argumento é mantido por retrocompatibilidade.

  user_line(frame)

    Chamado a partir de `dispatch_line()` quando `stop_here()` ou `break_here()` retornam `True`.

  user_return(frame, return_value)

    Chamado a partir de `dispatch_return()` quando `stop_here()` retorna `True`.

  user_exception(frame, exc_info)

    Chamado a partir de `dispatch_exception()` quando `stop_here()` retorna `True`.

  do_clear(arg)

    Manipula como um ponto de interrupção deve ser removido quando for temporário.

    Esse método deve ser implementado por classes derivadas.

  As classes derivadas e os clientes podem chamar os métodos a seguir para afetar o estado de stepping.

  set_step()

    Parar após uma linha de código.

  set_next(frame)

    Parar na próxima linha no frame fornecido ou abaixo dele.

  set_return(frame)

    Parar ao retornar do frame fornecido.

  set_until(frame, lineno=None)

    Parar quando a linha com lineno maior que a atual for alcançada ou ao retornar do frame atual.

  set_trace([frame])

    Inicia a depuração a partir de frame. Se frame não for especificado, a depuração começa a partir do frame do chamador.

    Alterado na versão 3.13: `set_trace()` entrará no depurador imediatamente, em vez da próxima linha de código a ser executada.

  set_continue()

    Pare somente nos pontos de interrupção ou quando terminar. Se não houver pontos de interrupção, defina o sistema função de rastreamento como `None`.

  set_quit()

    Defina o atributo `quitting` como `True`. Isso levanta `BdbQuit` na próxima chamada de um dos métodos `dispatch_*()`.

  Classes derivadas e clientes podem chamar os métodos a seguir para manipular pontos de interrupção. Esses métodos retornam uma string contendo uma mensagem de erro se algo der errado, ou `None` se tudo estiver correto.

  set_break(filename, lineno, temporary=False, cond=None, funcname=None)

    Define um novo ponto de interrupção. Se a linha lineno não existir para o filename passado como argumento, retorna uma mensagem de erro. O filename deve estar na forma canônica, conforme descrito no método `canonic()`.

  clear_break(filename, lineno)

    Exclui os pontos de interrupção em filename e lineno. Se nenhum tiver sido definido, retorna uma mensagem de erro.

  clear_bpbynumber(arg)

    Exclui o ponto de interrupção cujo índice é arg em `Breakpoint.bpbynumber`. Se arg não for numérico ou estiver fora do intervalo, retorna uma mensagem de erro.

  clear_all_file_breaks(filename)

    Exclui todos os pontos de interrupção em filename. Se nenhum tiver sido definido, retorna uma mensagem de erro.

  clear_all_breaks()

    Exclui todos os pontos de interrupção existentes. Se nenhum tiver sido definido, retorna uma mensagem de erro.

  get_bpbynumber(arg)

    Retorna o ponto de interrupção especificado pelo número fornecido. Se arg for uma string, ele será convertido para um número. Se arg for uma string não numérica, se o ponto de interrupção nunca tiver existido ou tiver sido excluído, uma `ValueError` será levantada.

    Adicionado na versão 3.2.

  get_break(filename, lineno)

    Retorna `True` se houver um ponto de interrupção para lineno em filename.

  get_breaks(filename, lineno)

    Retorna todos os pontos de interrupção para lineno em filename, ou uma lista vazia se nenhum estiver definido.

  get_file_breaks(filename)

    Retorna todos os pontos de interrupção em filename, ou uma lista vazia se nenhum estiver definido.

  get_all_breaks()

    Retorna todos os pontos de interrupção definidos.

  Classes derivadas e clientes podem chamar os métodos a seguir para obter uma estrutura de dados que represente um stack trace (situação da pilha de execução).

  get_stack(f, t)

    Retorna uma lista de tuplas (frame, lineno) em um stack trace e um tamanho.

    O frame chamado mais recentemente é o último da lista. O tamanho é o número de frames abaixo do frame onde o depurador foi invocado.

  format_stack_entry(frame_lineno, lprefix=': ')

    Retorna uma string com informações sobre uma entrada da pilha, que é uma tupla `(frame, lineno)`. A string retornada contém:

    - O nome de arquivo canônico que contém o quadro.

    - O nome da função ou `"<lambda>"`.

    - O argumento de entrada.

    - O valor de retorno.

    - A linha de código (se existir).

  Os dois métodos a seguir podem ser chamados pelos clientes para usar um depurador e depurar uma instrução, fornecida como uma string.

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

    Depura uma instrução executada por meio da função `exec()`. globals assume por padrão `__main__.__dict__`, locals assume por padrão globals.

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

    Depura uma expressão executada por meio da função `eval()`. globals e locals têm o mesmo significado que em `run()`.

  runctx(cmd, globals, locals)

    Por retrocompatibilidade. Chama o método `run()`.

  runcall(func, /, *args, **kwds)

    Depura uma única chamada de função e retorna seu resultado.

Por fim, o módulo define as funções a seguir:

bdb.checkfuncname(b, frame)

  Retorna `True` se devemos interromper aqui, dependendo da forma como o `Breakpoint` foi configurado.

  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)

  Retorna `(active breakpoint, delete temporary flag)` ou `(None, None)` como o ponto de interrupção sobre o qual agir.

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

  Se essa entrada não existir, será retornado `(None, None)`.

bdb.set_trace()

  Inicie a depuração com uma instância de `Bdb` a partir do frame do chamador.