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 da 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.
Novo 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=".")