Horology

Conveniently measures the time of your loops, contexts and functions.

Installation

Horology can be installed with pip. It has no dependencies.

pip install horology

Usage

The following 3 tools will let you measure practically any part of your Python code.

Timing an iterable (list, tuple, generator, etc.)

Quick example

from horology import Timed

animals = ['cat', 'dog', 'crocodile']

for x in Timed(animals):
    feed(x)

Result:

iteration    1: 12 s
iteration    2: 8 s
iteration    3: 100 s

total 3 iterations in 120 s
min/median/max: 8/12/100 s
average (std): 40 (52) s

Customization

You can specify where (if at all) you want each iteration and summary to be printed, e.g.:

for x in Timed(animals, unit='ms',
               iteration_print_fn=logger.debug,
               summary_print_fn=logger.info):
    feed(x)

With sparkline=True, the summary ends with a sparkline of iteration times, e.g. ▄▁▁█▁.

Timing a function with a @timed decorator

Quick example

from horology import timed


@timed
def foo():
    ...

Result:

>>> foo()
foo: 7.12 ms

Customization

Choose time unit and name:

@timed(unit='s', name='Processing took')
def bar():
    ...

Result:

>>> bar()
Processing took 0.185 s

Timing part of code with a Timing context

Quick example

Just wrap your code using a with statement:

from horology import Timing

with Timing(name='Important calculations:'):
    ...

Result:

Important calculations: 12.4 s

Customization

You can suppress default printing and directly use measured time (also within the context):

with Timing(print_fn=None) as t:
    ...

make_use_of(t.interval)

Async code

All three tools work with async code as well:

@timed
async def fetch(url):
    ...

async def main():
    await fetch(url)  # measured until the coroutine finishes

    async with Timing(name='Downloading:'):
        ...

    async for page in Timed(fetch_pages()):
        ...

Failures

If a function decorated with @timed or the code inside Timing raises an exception (also KeyboardInterrupt), the time elapsed is printed with (failed) and also added to the exception, so you can see it right in the traceback, even if printing is turned off:

Traceback (most recent call last):
  ...
TimeoutError: https://example.com
horology: fetch: 1.5 s (failed)

Time units

Time units are by default automatically adjusted, for example you will see foo: 7.12 ms rather than foo: 0.007 s. If you don't like it, you can override this by setting the unit argument with one of these names: ['ns', 'us', 'ms', 's', 'min', 'h', 'd'].

Contributions

Contributions are welcome, see contribution guide.

Internals

Horology internally measures time with perf_counter, which provides the highest available resolution, see docs.