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