trace
— Rastreia ou acompanha a execução de instruções Python¶
Código-fonte: Lib/trace.py
O módulo trace
permite que você rastreie a execução do programa, gere listagens de cobertura de instrução anotada, imprima relações de chamador/receptor e funções de lista executadas durante a execução de um programa. Ele pode ser usado em outro programa ou na linha de comando.
Ver também
- Coverage.py
Uma popular ferramenta de cobertura de terceiros que fornece saída HTML junto com recursos avançados, como cobertura de ramificações.
Uso na linha de comando¶
O módulo trace
pode ser chamado a partir da linha de comando. Pode ser tão simples quanto:
python -m trace --count -C . somefile.py ...
O comando acima irá executar algumarquivo.py
e gerar listagens anotadas de todos os módulos Python importados durante a execução para o diretório atual.
- --help¶
Exibe o modo de uso e sai.
- --version¶
Exibe a versão do módulo e sai.
Adicionado na versão 3.8: Adicionada a opção --module
que permite executar um módulo executável.
Opções principais¶
Pelo menos uma das seguintes opções deve ser especificada ao invocar trace
. A opção --listfuncs
é mutuamente exclusiva com as opções --trace
e --count
. Quando --listfuncs
é fornecida, nem --count
nem --trace
são aceitas, e vice-versa.
- -c, --count¶
Produz um conjunto de arquivos de listagem anotada após a conclusão do programa que mostra quantas vezes cada instrução foi executada. Veja também
--coverdir
,--file
e--no-report
abaixo.
- -t, --trace¶
Exibe linhas como elas são executadas.
- -l, --listfuncs¶
Exibe as funções executadas executando o programa.
- -r, --report¶
Produz uma lista anotada de uma execução de programa anterior que usava a opção
--count
e--file
. Isso não executa nenhum código.
- -T, --trackcalls¶
Exibe os relacionamentos de chamada expostos ao executar o programa.
Modificadores¶
- -f, --file=<file>¶
Nome de um arquivo para acumular contagens em várias execuções de rastreamento. Deve ser usado com a opção
--count
.
- -C, --coverdir=<dir>¶
Diretório para onde vão os arquivos de relatório. O relatório de cobertura para
pacote.módulo
é escrito em arquivodir/pacote/módulo.cover
.
- -m, --missing¶
Ao gerar listagens anotadas, marca as linhas que não foram executadas com
>>>>>>
.
- -s, --summary¶
Ao usar
--count
ou--report
, escreve um breve resumo no stdout para cada arquivo processado.
- -R, --no-report¶
Não gera listagens anotadas. Isso é útil se você pretende fazer várias execuções com
--count
, e então produzir um único conjunto de listagens anotadas no final.
- -g, --timing¶
Prefixa cada linha com o tempo desde o início do programa. Usado apenas durante o rastreamento.
Filtros¶
Essas opções podem ser repetidas várias vezes.
- --ignore-module=<mod>¶
Ignora cada um dos nomes de módulo fornecidos e seus submódulos (se for um pacote). O argumento pode ser uma lista de nomes separados por uma vírgula.
- --ignore-dir=<dir>¶
Ignora todos os módulos e pacotes no diretório e subdiretórios nomeados. O argumento pode ser uma lista de diretórios separados por
os.pathsep
.
Interface programática¶
- class trace.Trace(count=1, trace=1, countfuncs=0, countcallers=0, ignoremods=(), ignoredirs=(), infile=None, outfile=None, timing=False)¶
Cria um objeto para rastrear a execução de uma única instrução ou expressão. Todos os parâmetros são opcionais. count ativa a contagem de números de linha. trace ativa o rastreamento de execução de linha. countfuncs ativa a listagem das funções chamadas durante a execução. countcallers ativa o rastreamento de relacionamento de chamada. ignoremods é uma lista de módulos ou pacotes a serem ignorados. ignoreirs é uma lista de diretórios cujos módulos ou pacotes devem ser ignorados. infile é o nome do arquivo do qual deve ler as informações de contagem armazenadas. outfile é o nome do arquivo no qual deve escrever as informações de contagem atualizadas. timing ativa a exibição de um carimbo de data/hora relativo ao momento em que o rastreamento foi iniciado.
- run(cmd)¶
Executa o comando e reúne estatísticas da execução com os parâmetros de rastreamento atuais. cmd deve ser uma string ou objeto código, adequado para passar para
exec()
.
- runctx(cmd, globals=None, locals=None)¶
Executa o comando e reúne estatísticas da execução com os parâmetros de rastreamento atuais, nos ambientes global e local definidos. Se não for definido, globals e locals usam como padrão dicionários vazios.
- runfunc(func, /, *args, **kwds)¶
Chama func com os argumentos fornecidos sob controle do objeto
Trace
com os parâmetros de rastreamento atuais.
- results()¶
Retorna um objeto
CoverageResults
que contém os resultados cumulativos de todas as chamadas anteriores pararun
,runctx
erunfunc
para a instânciaTrace
fornecida. Não redefine os resultados de rastreamento acumulados.
- class trace.CoverageResults¶
Um contêiner para resultados de cobertura, criado por
Trace.results()
. Não deve ser criado diretamente pelo usuário.- update(other)¶
Mescla dados de outro objeto
CoverageResults
.
- write_results(show_missing=True, summary=False, coverdir=None)¶
Escreve os resultados da cobertura. Defina show_missing para mostrar as linhas que não tiveram ocorrências. Defina o summary para incluir na saída o resumo da cobertura por módulo. coverdir especifica o diretório no qual os arquivos de resultados de cobertura serão enviados. Se for
None
, os resultados de cada arquivo de origem são colocados em seu diretório.
Um exemplo simples que demonstra o uso da interface programática:
import sys
import trace
# create a Trace object, telling it what to ignore, and whether to
# do tracing or line-counting or both.
tracer = trace.Trace(
ignoredirs=[sys.prefix, sys.exec_prefix],
trace=0,
count=1)
# run the new command using the given tracer
tracer.run('main()')
# make a report, placing output in the current directory
r = tracer.results()
r.write_results(show_missing=True, coverdir=".")