"timeit" --- Mede o tempo de execução de pequenos trechos de código
*******************************************************************

**Código-fonte:** Lib/timeit.py

======================================================================

Este módulo fornece uma maneira simples de cronometrar pequenos
trechos do código Python. Ele tem uma Interface de Linha de Comando e
um chamável.  Ele evita uma série de armadilhas comuns para medir os
tempos de execução de um script. Veja também o capítulo "Algorithms"
de Tim Peters, na segunda edição do *Python Cookbook*, publicado pela
O'Reilly.


Exemplos básicos
================

O exemplo a seguir mostra como a Interface de Linha de Comando pode
ser usado para comparar três expressões diferentes:

   $ python -m timeit "'-'.join(str(n) for n in range(100))"
   10000 loops, best of 5: 30.2 usec per loop
   $ python -m timeit "'-'.join([str(n) for n in range(100)])"
   10000 loops, best of 5: 27.5 usec per loop
   $ python -m timeit "'-'.join(map(str, range(100)))"
   10000 loops, best of 5: 23.2 usec per loop

Isso pode ser obtido da interface Interface em Python

   >>> import timeit
   >>> timeit.timeit('"-".join(str(n) for n in range(100))', number=10000)
   0.3018611848820001
   >>> timeit.timeit('"-".join([str(n) for n in range(100)])', number=10000)
   0.2727368790656328
   >>> timeit.timeit('"-".join(map(str, range(100)))', number=10000)
   0.23702679807320237

Um chamável também pode ser passado para a Interface em Python:

   >>> timeit.timeit(lambda: "-".join(map(str, range(100))), number=10000)
   0.19665591977536678

Observe, entretanto, que "timeit()" determinará automaticamente o
número de repetições somente quando a interface de linha de comando
for usada. Na seção Exemplos você encontrará exemplos mais avançados.


Interface em Python
===================

Este módulo define três funções e uma classe pública:

timeit.timeit(stmt='pass', setup='pass', timer=<default timer>, number=1000000, globals=None)

   Cria uma instância de "Timer" com o código de *setup* e a função
   *timer* função para executar o método "timeit()" com o total de
   execuções informado em *number*. O argumento opcional *globals*
   especifica um espaço de nomes no qual o código será executado.

   Alterado na versão 3.5: O parâmetro opcional *globals* foi
   adicionado.

timeit.repeat(stmt='pass', setup='pass', timer=<default timer>, repeat=5, number=1000000, globals=None)

   Cria uma instância "Timer" com a instrução fornecida, o código de
   *setup* e a função *timer* e para executar o método "repeat()" com
   o total de execuções informando em *repeat* e o *número* de
   execuções fornecidos. O argumento opcional *globals* especifica um
   espaço de nomes no qual executar o código.

   Alterado na versão 3.5: O parâmetro opcional *globals* foi
   adicionado.

   Alterado na versão 3.7: Valor padrão de *repetição* mudou de 3 para
   5.

timeit.default_timer()

   O cronômetro padrão, que é sempre time.perf_counter(), retorna
   segundos com ponto flutuante. Uma alternativa,
   time.perf_counter_ns, retorna um inteiro em nanossegundos.

   Alterado na versão 3.3: "time.perf_counter()" é o cronômetro padrão
   agora.

class timeit.Timer(stmt='pass', setup='pass', timer=<timer function>, globals=None)

   Classe para cronometrar a velocidade de execução de pequenos
   trechos de código.

   O construtor recebe uma instrução a ser cronometrada, uma instrução
   adicional usada para configuração e uma função de timer. Ambas as
   instruções têm como padrão "'pass'"; a função de timer é dependente
   da plataforma (veja a string do documento do módulo). *stmt* e
   *setup* também podem conter múltiplas instruções separadas por ";"
   ou novas linhas, desde que não contenham literais de string
   multilinhas. A instrução será, por padrão, executada dentro do
   espaço de nomes do *timeit*; esse comportamento pode ser controlado
   passando um espaço de nomes para *globals*.

   Para medir o tempo de execução da primeira instrução use o método
   "timeit()". Os métodos "repeat()" e "autorange()" são convenientes
   para chamar "timeit()" várias vezes.

   O tempo de execução de *setup* é excluído do tempo total de
   execução cronometrado.

   Os parâmetros *stmt* e *setup* também podem receber objetos que
   podem ser chamados sem argumentos. Isso incorporará chamadas a eles
   em uma função de timer que será executada por "timeit()". Observe
   que a sobrecarga de temporização é um pouco maior neste caso por
   causa das chamadas de função extras.

   Alterado na versão 3.5: O parâmetro opcional *globals* foi
   adicionado.

   timeit(number=1000000)

      Mede o tempo para a quantidade *number* de execuções da
      instrução principal. Isso executa a instrução setup uma vez e,
      em seguida, retorna o tempo necessário para executar a instrução
      principal várias vezes. O temporizador padrão retorna segundos
      como um float. O argumento é o número de vezes que o laço passa,
      com padrão de um milhão. A instrução principal, a instrução de
      configuração e a função de timer a ser usada são passadas para o
      construtor.

      Nota:

        Por padrão, "timeit()" desativa temporariamente *coleta de
        lixo* durante a temporização. A vantagem dessa abordagem é que
        ela torna temporizações independentes mais comparáveis. A
        desvantagem é que o GC pode ser um componente importante do
        desempenho da função que está sendo medida. Se for assim, o GC
        pode ser reativado como a primeira instrução na string
        *setup*. Por exemplo:

           timeit.Timer('for i in range(10): oct(i)', 'gc.enable()').timeit()

   autorange(callback=None)

      Determina automaticamente quantas vezes chamar "timeit()".

      Esta é uma função de conveniência que chama "timeit()"
      repetidamente para que o tempo total seja >= 0,2 segundos,
      retornando o eventual (número de voltas, tempo gasto para esse
      número de voltas). Ela chama "timeit()" com números crescentes
      da sequência 1, 2, 5, 10, 20, 50, ... até que o tempo gasto seja
      de pelo menos 0,2 segundos.

      Se *callback* for fornecido e não for "None", ele será chamado
      após cada tentativa e tem dois argumento: "callback(number,
      time_taken)".

      Adicionado na versão 3.6.

   repeat(repeat=5, number=1000000)

      Chama "timeit()" algumas vezes.

      Esse é um função de conveniência que chama o "timeit()"
      repetidamente e retorna uma lista de resultados.  O primeiro
      argumento especifica quantas vezes deve chamar o "timeit()".  O
      segundo argumento especifica o argumento *number* para
      "timeit()".

      Nota:

        É tentador calcular a média e o desvio padrão do vetor de
        resultados e relatá-los. No entanto, isso não é muito útil. Em
        um caso típico, o menor valor fornece um limite inferior para
        a velocidade com que sua máquina pode executar o trecho de
        código fornecido; valores mais altos no vetor de resultados
        normalmente não são causados pela variabilidade na velocidade
        do Python, mas por outros processos que interferem na precisão
        do seu tempo. Portanto, o "min()" do resultado é provavelmente
        o único número no qual você deve se interessar. Depois disso,
        você deve analisar o vetor inteiro e aplicar o bom senso em
        vez de estatística.

      Alterado na versão 3.7: Valor padrão de *repetição* mudou de 3
      para 5.

   print_exc(file=None)

      Função auxiliar para imprimir um traceback do código
      cronometrado.

      Uso típico:

         t = Timer(...)       # fora do try/except
         try:
             t.timeit(...)    # ou t.repeat(...)
         except Exception:
             t.print_exc()

      A vantagem em relação ao traceback padrão é que as linhas de
      origem no modelo compilado serão exibidas.  O argumento opcional
      *file* direciona para onde o traceback é enviado; o padrão é
      "sys.stderr".


Interface de Linha de Comando
=============================

Quando chamado como um programa a partir da linha de comando, as
seguintes opções estão disponíveis:

   python -m timeit [-n N] [-r N] [-u U] [-s S] [-p] [-v] [-h] [instrução ...]

As seguintes opções são permitidas

-n N, --number=N

   Quantas vezes deve executar 'statement'

-r N, --repeat=N

   Quantidade de vezes para repetir o cronômetro (o valor padrão é 5)

-s S, --setup=S

   instrução a ser executada apenas uma vez e quando iniciada (padrão
   "pass" )

-p, --process

   mede apenas o tempo de processamento, e não o tempo total de
   execução, usando "time.process_time()" em vez de
   "time.perf_counter()", que é o padrão

   Adicionado na versão 3.3.

-u, --unit=U

   especifique uma unidade de tempo para a saída do cronômetro; pode
   selecionar "nsec", "usec", "msec", ou "sec"

   Adicionado na versão 3.5.

-v, --verbose

   imprime resultados brutos de tempo; repetir para obter mais
   precisão de dígitos

-h, --help

   imprime uma mensagem curta de uso e sai

Uma instrução multilinha pode ser fornecida especificando cada linha
como um argumento de instrução separado; linhas indentadas são
possíveis colocando um argumento entre aspas e usando espaços à
esquerda. Múltiplas opções "-s" são tratadas de forma semelhante.

Se "-n" não for informada, um número adequado de loops será calculado
tentando adicionar números numa sequência como 1, 2, 5, 10, 20, 50,
... até que o tempo total seja de pelo menos 0,2 segundos.

As medições de "default_timer()" podem ser afetadas por outros
programas em execução na mesma máquina, portanto, a melhor coisa a
fazer quando uma cronometragem precisa é repeti-la algumas vezes e
usar o melhor tempo. A opção "-r" é boa para isso; o padrão de 5
repetições provavelmente é suficiente na maioria dos casos. Você pode
usar "time.process_time()" para medir o tempo de CPU.

Nota:

  Há uma certa sobrecarga padrão associada à execução de uma instrução
  *pass*. O código aqui não tenta ocultá-lo, mas você deve estar
  ciente disso.  A sobrecarga padrão pode ser medida invocando pelo
  programa sem argumento, e pode ser diferente entre diferentes
  versões Python.


Exemplos
========

É possível fornecer uma instrução de configuração que é executada
apenas uma vez no início:

   $ python -m timeit -s "text = 'sample string'; char = 'g'" "char in text"
   5000000 loops, best of 5: 0.0877 usec per loop
   $ python -m timeit -s "text = 'sample string'; char = 'g'" "text.find(char)"
   1000000 loops, best of 5: 0.342 usec per loop

Na saída, existem três campos. A contagem de laços, que informa
quantas vezes o corpo da instrução foi executado por repetição do laço
de temporização. A contagem de repetições ('melhor de 5') que informa
quantas vezes o laço de temporização foi repetido e, finalmente, o
tempo que o corpo da instrução levou, em média, na melhor repetição do
laço de temporização. Ou seja, o tempo necessário para a repetição
mais rápida dividido pela contagem de interações.

   >>> import timeit
   >>> timeit.timeit('char in text', setup='text = "sample string"; char = "g"')
   0.41440500499993504
   >>> timeit.timeit('text.find(char)', setup='text = "sample string"; char = "g"')
   1.7246671520006203

O mesmo pode ser feito usando a classe "Timer" e seus métodos:

   >>> import timeit
   >>> t = timeit.Timer('char in text', setup='text = "sample string"; char = "g"')
   >>> t.timeit()
   0.3955516149999312
   >>> t.repeat()
   [0.40183617287970225, 0.37027556854118704, 0.38344867356679524, 0.3712595970846668, 0.37866875250654886]

Os exemplos a seguir mostram como cronometrar expressões que contêm
várias linhas. Aqui comparamos o custo de usar "hasattr()" vs.
"try"/"except" para testar atributos de objetos presentes e ausentes:

   $ python -m timeit "try:" "  str.__bool__" "except AttributeError:" "  pass"
   20000 loops, best of 5: 15.7 usec per loop
   $ python -m timeit "if hasattr(str, '__bool__'): pass"
   50000 loops, best of 5: 4.26 usec per loop

   $ python -m timeit "try:" "  int.__bool__" "except AttributeError:" "  pass"
   200000 loops, best of 5: 1.43 usec per loop
   $ python -m timeit "if hasattr(int, '__bool__'): pass"
   100000 loops, best of 5: 2.23 usec per loop

   >>> import timeit
   >>> # atributo está em falta
   >>> s = """\
   ... try:
   ...     str.__bool__
   ... except AttributeError:
   ...     pass
   ... """
   >>> timeit.timeit(stmt=s, number=100000)
   0.9138244460009446
   >>> s = "if hasattr(str, '__bool__'): pass"
   >>> timeit.timeit(stmt=s, number=100000)
   0.5829014980008651
   >>>
   >>> # atributo está presente
   >>> s = """\
   ... try:
   ...     int.__bool__
   ... except AttributeError:
   ...     pass
   ... """
   >>> timeit.timeit(stmt=s, number=100000)
   0.04215312199994514
   >>> s = "if hasattr(int, '__bool__'): pass"
   >>> timeit.timeit(stmt=s, number=100000)
   0.08588060699912603

Para dar ao módulo "timeit" acesso as funções que você definiu, você
pode passar o parâmetro *setup*, que contém um instrução de importar:

   def test():
       """Stupid test function"""
       L = [i for i in range(100)]

   if __name__ == '__main__':
       import timeit
       print(timeit.timeit("test()", setup="from __main__ import test"))

Outra opção é passar "globals()" para o parâmetro *globals*, o que
fará com que o código seja executado em seu espaço de nomes global.
Isso pode ser mais conveniente do que especificar individualmente
imports:

   def f(x):
       return x**2
   def g(x):
       return x**4
   def h(x):
       return x**8

   import timeit
   print(timeit.timeit('[func(42) for func in (f,g,h)]', globals=globals()))
