ubelt.util_time module

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

Variables:

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

Example

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

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

starts the timer

toc()

stops the timer

class ubelt.util_time.Timerit(num, label=None, bestof=3, 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 utool.util_time Timerit python -m utool.util_time Timerit:0 python -m utool.util_time Timerit:1

Example

>>> num = 15
>>> t1 = Timerit(num, verbose=2)
>>> 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)
>>> # <you can now access Timerit attributes>
>>> print('t1.total_time = %r' % (t1.total_time,))
>>> assert t1.total_time > 0
>>> assert t1.n_loops == t1.num
>>> assert t1.n_loops == num

Example

>>> num = 10
>>> # If the timer object is unused, time will still be recorded,
>>> # but with less precision.
>>> for _ in Timerit(num, 'imprecise'):
>>>     math.factorial(10000)
>>> # Using the timer object results in the most precise timings
>>> for timer in Timerit(num, 'precise'):
>>>     with timer: math.factorial(10000)

call(func, *args, **kwargs)

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

Returns:Use ave_secs, min, or mean to get a scalar. Return type:self (Timerit)

Example

>>> ave_sec = Timerit(num=10).call(math.factorial, 50).ave_secs
>>> assert ave_sec > 0

ave_secs

The expected execution time of the timed code snippet in seconds. This is the minimum value recorded over all runs.

SeeAlso:

self.min self.mean self.std

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. ‘’‘

Example

>>> 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.

Note

This is typically less informative than simply looking at the min

Example

>>> 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.

Note

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

Example

>>> self = Timerit(num=10, verbose=1)
>>> self.call(math.factorial, 50)
>>> assert self.std() >= 0

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

make an iso8601 timestamp

CommandLine:

python -m ubelt.util_time timestamp

Example

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