ubelt.timerit module

First, Timer is a context manager that times a block of indented code. Also has tic and toc methods for a more matlab like feel.

Next, Timerit is an alternative to the builtin timeit module. I think its better at least, maybe Tim Peters can show me otherwise. Perhaps there’s a reason it has to work on strings and can’t be placed around existing code like a with statement.

Example

>>> # xdoctest: +IGNORE_WANT
>>> #
>>> # The Timerit class allows for robust benchmarking based
>>> # It can be used in normal scripts by simply adjusting the indentation
>>> import math
>>> for timer in Timerit(num=12, verbose=3):
>>>     with timer:
>>>         math.factorial(100)
Timing for: 200 loops, best of 3
Timed for: 200 loops, best of 3
    body took: 331.840 µs
    time per loop: best=1.569 µs, mean=1.615 ± 0.0 µs
>>> # xdoctest: +SKIP
>>> # In Contrast, timeit is similar, but not having to worry about setup
>>> # and inputing the program as a string, is nice.
>>> import timeit
>>> timeit.timeit(stmt='math.factorial(100)', setup='import math')
1.12695...

Example

>>> # xdoctest: +IGNORE_WANT
>>> #
>>> # The Timer class can also be useful for quick checks
>>> #
>>> import math
>>> timer = Timer('Timer demo!', verbose=1)
>>> x = 100000  # the input for example output
>>> x = 10      # the input for test speed considerations
>>> with timer:
>>>     math.factorial(x)
tic('Timer demo!')
...toc('Timer demo!')=0.1959s
class ubelt.timerit.Timer(label='', verbose=None, newline=True)[source]

Bases: object

Measures time elapsed between a start and end point. Can be used as a with-statement context manager, or using the tic/toc api.

Parameters
  • label (str, default=’’) – identifier for printing

  • verbose (int, default=None) – verbosity flag, defaults to True if label is given

  • newline (bool, default=True) – if False and verbose, print tic and toc on the same line

Variables
  • elapsed (float) – number of seconds measured by the context manager

  • tstart (float) – time of last tic reported by self._time()

Example

>>> # Create and start the timer using the context manager
>>> import math
>>> timer = Timer('Timer test!', verbose=1)
>>> with timer:
>>>     math.factorial(10)
>>> assert timer.elapsed > 0
tic('Timer test!')
...toc('Timer test!')=...

Example

>>> # Create and start the timer using the tic/toc interface
>>> timer = Timer().tic()
>>> elapsed1 = timer.toc()
>>> elapsed2 = timer.toc()
>>> elapsed3 = timer.toc()
>>> assert elapsed1 <= elapsed2
>>> assert elapsed2 <= elapsed3
tic()[source]

starts the timer

toc()[source]

stops the timer

class ubelt.timerit.Timerit(num=1, label=None, bestof=3, unit=None, verbose=None)[source]

Bases: object

Reports the average time to run a block of code.

Unlike %timeit, Timerit can handle multiline blocks of code. It runs inline, and doesn’t depend on magic or strings. Just indent your code and place in a Timerit block. See https://github.com/Erotemic/vimtk for vim functions that will insert one of these in for you (ok that part is a little magic).

Parameters
  • num (int, default=1) – number of times to run the loop

  • label (str, default=None) – identifier for printing

  • bestof (int, default=3) – takes the max over this number of trials

  • unit (str) – what units time is reported in

  • verbose (int) – verbosity flag, defaults to True if label is given

Variables
  • object (measures - labeled measurements taken by this) –

  • measurements (rankings - ranked) –

Example

>>> import math
>>> num = 3
>>> t1 = Timerit(num, label='factorial', verbose=1)
>>> for timer in t1:
>>>     # <write untimed setup code here> this example has no setup
>>>     with timer:
>>>         # <write code to time here> for example...
>>>         math.factorial(100)
Timed best=..., mean=... for factorial
>>> # <you can now access Timerit attributes>
>>> assert t1.total_time > 0
>>> assert t1.n_loops == t1.num
>>> assert t1.n_loops == num

Example

>>> # xdoc: +IGNORE_WANT
>>> import math
>>> num = 4
>>> # If the timer object is unused, time will still be recorded,
>>> # but with less precision.
>>> for _ in Timerit(num, 'concise', bestof=2, verbose=2):
>>>     math.factorial(100)
Timed concise for: 4 loops, best of 2
    time per loop: best=1.637 µs, mean=1.935 ± 0.3 µs
>>> # Using the timer object results in the most precise timings
>>> for timer in Timerit(num, 'precise', bestof=2, verbose=3):
>>>     with timer: math.factorial(100)
Timed precise for: 4 loops, best of 2
    body took: 8.696 µs
    time per loop: best=1.754 µs, mean=1.821 ± 0.1 µs
reset(label=None, measures=False)[source]

clears all measurements, allowing the object to be reused

Parameters
  • label (str | None) – change the label if specified

  • measures (bool, default=False) – if True reset measures

Example

>>> import math
>>> ti = Timerit(num=10, unit='us', verbose=True)
>>> _ = ti.reset(label='10!').call(math.factorial, 10)
Timed best=...s, mean=...s for 10!
>>> _ = ti.reset(label='20!').call(math.factorial, 20)
Timed best=...s, mean=...s for 20!
>>> _ = ti.reset().call(math.factorial, 20)
Timed best=...s, mean=...s for 20!
>>> _ = ti.reset(measures=True).call(math.factorial, 20)
call(func, *args, **kwargs)[source]

Alternative way to time a simple function call using condensed syntax.

Returns

self :

Use min, or mean to get a scalar. Use print to output a report to stdout.

Return type

‘Timerit’

Example

>>> import math
>>> time = Timerit(num=10).call(math.factorial, 50).min()
>>> assert time > 0
property rankings

Orders each list of measurements by ascending time

Example

>>> import math
>>> ti = Timerit(num=1)
>>> _ = ti.reset('a').call(math.factorial, 5)
>>> _ = ti.reset('b').call(math.factorial, 10)
>>> _ = ti.reset('c').call(math.factorial, 20)
>>> ti.rankings
>>> ti.consistency
property consistency

” Take the hamming distance between the preference profiles to as a measure of consistency.

min()[source]

The best time overall.

This is typically the best metric to consider when evaluating the execution time of a function. To understand why consider this quote from the docs of the original timeit module:

‘’’ In a typical case, the lowest value gives a lower bound for how fast your machine can run the given code snippet; higher values in the result vector are typically not caused by variability in Python’s speed, but by other processes interfering with your timing accuracy. So the min() of the result is probably the only number you should be interested in. ‘’’

Returns

minimum measured seconds over all trials

Return type

float

Example

>>> import math
>>> self = Timerit(num=10, verbose=0)
>>> self.call(math.factorial, 50)
>>> assert self.min() > 0
mean()[source]

The mean of the best results of each trial.

Returns

mean of measured seconds

Return type

float

Note

This is typically less informative than simply looking at the min. It is recommended to use min as the expectation value rather than mean in most cases.

Example

>>> import math
>>> self = Timerit(num=10, verbose=0)
>>> self.call(math.factorial, 50)
>>> assert self.mean() > 0
std()[source]

The standard deviation of the best results of each trial.

Returns

standard deviation of measured seconds

Return type

float

Note

As mentioned in the timeit source code, the standard deviation is not often useful. Typically the minimum value is most informative.

Example

>>> import math
>>> self = Timerit(num=10, verbose=1)
>>> self.call(math.factorial, 50)
>>> assert self.std() >= 0
report(verbose=1)[source]

Creates a human readable report

Parameters

verbose (int) – verbosity level. Either 1, 2, or 3.

Returns

the report

Return type

str

SeeAlso:

Timerit.print()

Example

>>> import math
>>> ti = Timerit(num=1).call(math.factorial, 5)
>>> print(ti.report(verbose=1))
Timed best=...s, mean=...s
print(verbose=1)[source]

Prints human readable report using the print function

Parameters

verbose (int) – verbosity level

SeeAlso:

Timerit.report()

Example

>>> import math
>>> Timerit(num=10).call(math.factorial, 50).print(verbose=1)
Timed best=...s, mean=...s
>>> Timerit(num=10).call(math.factorial, 50).print(verbose=2)
Timed for: 10 loops, best of 3
    time per loop: best=...s, mean=...s
>>> Timerit(num=10).call(math.factorial, 50).print(verbose=3)
Timed for: 10 loops, best of 3
    body took: ...
    time per loop: best=...s, mean=...s