ubelt.util_time module

Timerit now exists in a standalone pip-installable module. The source code lives in its own github repo here: https://github.com/Erotemic/timerit

Example

>>> # xdoctest: +IGNORE_WANT
>>> import math
>>> import ubelt as ub
>>> timer = ub.Timer('Timer demo!', verbose=1)
>>> with timer:
>>>     math.factorial(100000)
tic('Timer demo!')
...toc('Timer demo!')=0.1453s

Example

>>> # xdoctest: +IGNORE_WANT
>>> import math
>>> import ubelt as ub
>>> for _ in ub.Timerit(num=200, verbose=3):
>>>     math.factorial(10000)
Timing for 200 loops
Timed for: 200 loops, best of 3
    time per loop: best=2.055 ms, mean=2.145 ± 0.083 ms

ubelt.util_time.timestamp(method='iso8601')

make an iso8601 timestamp suitable for use in filenames

Parameters:method (str, default=’iso8601’) – type of timestamp

Example

>>> stamp = timestamp()
>>> print('stamp = {!r}'.format(stamp))
stamp = ...-...-...T...

class ubelt.util_time.Timer(label='', verbose=None, newline=True)

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) – identifier for printing, defaults to ‘’
• verbose (int) – verbosity flag, defaults to True if label is given
• newline (bool) – if False and verbose, print tic and toc on the same line, defaults to True

Variables:

• elapsed (float) – number of seconds measured by the context manager
• tstart (float) – time of last tic reported by self._time()

CommandLine:

python -m timerit.core Timer

Example

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

Example

>>> # Create and start the timer using the tic/toc interface
>>> from timerit import Timer
>>> timer = Timer().tic()
>>> elapsed1 = timer.toc()
>>> elapsed2 = timer.toc()
>>> elapsed3 = timer.toc()
>>> assert elapsed1 <= elapsed2
>>> assert elapsed2 <= elapsed3

tic()

starts the timer

toc()

stops the timer

class ubelt.util_time.Timerit(num=1, label=None, bestof=3, unit=None, verbose=None)

Bases: object

Reports the average time to run a block of code.

Unlike timeit, Timerit can handle multiline blocks of code

Parameters:

• num (int) – number of times to run the loop
• label (str) – identifier for printing
• bestof (int) – takes the max over this number of trials
• verbose (int) – verbosity flag, defaults to True if label is given

CommandLine:

python -m timerit.core Timerit:0

Example

>>> from timerit import Timerit
>>> import math
>>> num = 15
>>> 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(10000)
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
>>> from timerit import Timerit
>>> num = 10
>>> # If the timer object is unused, time will still be recorded,
>>> # but with less precision.
>>> for _ in Timerit(num, 'concise', verbose=2):
>>>     math.factorial(10000)
Timed concise for: 10 loops, best of 3
    time per loop: best=4.954 ms, mean=4.972 ± 0.018 ms
>>> # Using the timer object results in the most precise timings
>>> for timer in Timerit(num, 'precise', verbose=3):
>>>     with timer: math.factorial(10000)
Timing precise for: 15 loops, best of 3
Timed precise for: 15 loops, best of 3
    time per loop: best=2.474 ms, mean=2.54 ± 0.046 ms

reset(label=None)

clears all measurements, allowing the object to be reused

Parameters:label (str, optional) – optionally change the label

Example

>>> from timerit import Timerit
>>> 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!

call(func, *args, **kwargs)

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

Returns:

Use min, or mean to get a scalar. Use print

to output a report to stdout.

Return type:self (Timerit)

Example

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

min()

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()

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()

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)

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)

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