"bdb" --- Debugger framework
****************************

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

      Novo 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 if a "Breakpoint" at (file, line) is temporary.

   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

      Verdadeiro se "Breakpoint" estiver habilitado.

   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.

   Novo na versão 3.1: O argumento *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()

      Set the "botframe", "stopframe", "returnframe" and "quitting"
      attributes with values ready to start debugging.

   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)

      If the debugger should stop on the current line, invoke the
      "user_line()" method (which should be overridden in subclasses).
      Raise a "BdbQuit" exception if the "Bdb.quitting" flag is set
      (which can be set from "user_line()").  Return a reference to
      the "trace_dispatch()" method for further tracing in that scope.

   dispatch_call(frame, arg)

      If the debugger should stop on this function call, invoke the
      "user_call()" method (which should be overridden in subclasses).
      Raise a "BdbQuit" exception if the "Bdb.quitting" flag is set
      (which can be set from "user_call()").  Return a reference to
      the "trace_dispatch()" method for further tracing in that scope.

   dispatch_return(frame, arg)

      If the debugger should stop on this function return, invoke the
      "user_return()" method (which should be overridden in
      subclasses). Raise a "BdbQuit" exception if the "Bdb.quitting"
      flag is set (which can be set from "user_return()").  Return a
      reference to the "trace_dispatch()" method for further tracing
      in that scope.

   dispatch_exception(frame, arg)

      If the debugger should stop at this exception, invokes the
      "user_exception()" method (which should be overridden in
      subclasses). Raise a "BdbQuit" exception if the "Bdb.quitting"
      flag is set (which can be set from "user_exception()").  Return
      a reference to the "trace_dispatch()" method for further tracing
      in that scope.

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

      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)

      Return True if any breakpoint exists for *frame*'s filename.

   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.

   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.

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

      Set the "quitting" attribute to "True".  This raises "BdbQuit"
      in the next call to one of the "dispatch_*()" methods.

   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.

      Novo na versão 3.2.

   get_break(filename, lineno)

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

      Debug a statement executed via the "exec()" function.  *globals*
      defaults to "__main__.__dict__", *locals* defaults to *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)

   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)

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

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

bdb.set_trace()

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