"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, backend='settrace')

   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.

   O argumento *backend* especifica o backend a ser usado pela "Bdb".
   Ele pode ser "'settrace'" ou "'monitoring'". "'settrace'" usa
   "sys.settrace()", que oferece a melhor retrocompatibilidade. O
   backend "'monitoring'" usa o novo "sys.monitoring", introduzido no
   Python 3.12, que pode ser muito mais eficiente porque pode
   desabilitar eventos não utilizados. Estamos tentando manter
   interfaces idênticas para ambos os backends, mas existem algumas
   diferenças. Os desenvolvedores de depuradores são incentivados a
   usar o backend "'monitoring'" para obter melhor desempenho.

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

   Alterado na versão 3.14: Adicionado o parâmetro *backend*.

   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.

   start_trace(self)

      Inicia o rastreamento. Para o backend "'settrace'", este método
      equivale a "sys.settrace(self.trace_dispatch)"

      Adicionado na versão 3.14.

   stop_trace(self)

      Para o rastreamento. Para o backend "'settrace'", este método
      equivale a "sys.settrace(None)"

      Adicionado na versão 3.14.

   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 de na 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
   desabilitar e reiniciar eventos a fim de obter melhor desempenho.
   Esses métodos só funcionam ao usar o backend "'monitoring'".

   disable_current_event()

      Desabilita o evento atual até a próxima vez que
      "restart_events()" for chamada. Isso é útil quando o depurador
      não está interessado na linha atual.

      Adicionado na versão 3.14.

   restart_events()

      Reinicia todos os eventos desabilitados. Essa função é chamada
      automaticamente nos métodos "dispatch_*" após a chamada dos
      métodos "user_*". Se os métodos "dispatch_*" não forem
      substituídos, os eventos desabilitados serão reiniciados após
      cada interação do usuário.

      Adicionado na versão 3.14.

   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.
