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.