# `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 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 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)

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