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 . algumarquivo.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 arquivo dir/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 para run, runctx e runfunc para a instância Trace 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, *, ignore_missing_files=False)

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.

Se ignore_missing_files for True, as contagens de cobertura para arquivos que não existem mais serão ignoradas silenciosamente. Caso contrário, um arquivo ausente vai levantar FileNotFoundError.

Alterado na versão 3.13: Adicionado o parâmetro ignore_missing_files.

Um exemplo simples que demonstra o uso da interface programática:

import sys
import trace

# cria um objeto Trace, dizendo a ele o que ignorar e se deve
# fazer rastreamento ou contagem de linhas ou ambos.
tracer = trace.Trace(
    ignoredirs=[sys.prefix, sys.exec_prefix],
    trace=0,
    count=1)

# executa o novo comando usando o rastreador fornecido
tracer.run('main()')

# faz um relatório, colocando a saída no diretório atual
r = tracer.results()
r.write_results(show_missing=True, coverdir=".")