https://github.com/mjmikulski/horology
timing functions, contexts and for-loops
https://github.com/mjmikulski/horology
hacktoberfest hacktoberfest2021 python
Last synced: 6 months ago
JSON representation
timing functions, contexts and for-loops
- Host: GitHub
- URL: https://github.com/mjmikulski/horology
- Owner: mjmikulski
- License: mit
- Created: 2018-08-13T23:11:07.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2025-10-26T13:36:27.000Z (8 months ago)
- Last Synced: 2025-10-26T15:29:32.408Z (8 months ago)
- Topics: hacktoberfest, hacktoberfest2021, python
- Language: Python
- Homepage:
- Size: 643 KB
- Stars: 88
- Watchers: 2
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/contributing.md
- License: LICENSE
Awesome Lists containing this project
README
# `Horology`
[](https://badge.fury.io/py/horology)
[](https://github.com/mjmikulski/horology/actions/workflows/tests.yaml)
[](https://github.com/mjmikulski/horology/actions/workflows/codeql.yaml)
[](https://pypi.org/project/horology/)
[](https://pypi.org/project/horology/)
[](https://pepy.tech/project/horology)
[](https://opensource.org/licenses/MIT)
Conveniently measures the time of your loops, contexts and functions.
## Installation
| horology version | compatible python |
|------------------|-------------------|
| 1.4.2 | 3.10-3.14 |
| 1.4.1 | 3.10-3.13 |
| 1.4 | 3.10-3.12 |
| 1.3 | 3.8-3.11 |
| 1.2 | 3.6-3.9 |
| 1.1 | 3.6-3.8 |
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
```python
from horology import Timed
animals = ['cat', 'dog', 'crocodile']
for x in Timed(animals):
feed(x)
```
Result:
```
iteration 1: 12.0 s
iteration 2: 8.00 s
iteration 3: 100 s
total 3 iterations in 120 s
min/median/max: 8.00/12.0/100 s
average (std): 40.0 (52.0) s
```
#### Customization
You can specify where (if at all) you want each iteration and summary to be printed, eg.:
```python
for x in Timed(animals, unit='ms',
iteration_print_fn=logger.debug,
summary_print_fn=logger.info):
feed(x)
```
### Timing a function with a `@timed` decorator
#### Quick example
```python
from horology import timed
@timed
def foo():
...
```
Result:
```
>>> foo()
foo: 7.12 ms
```
#### Customization
Chose time unit and name:
```python
@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
```python
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 context)
```python
with Timing(print_fn=None) as t:
...
make_use_of(t.interval)
```
## 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 welcomed, see [contribution guide](.github/contributing.md).
## Internals
Horology internally measures time with `perf_counter` which provides the *highest available resolution,*
see [docs](https://docs.python.org/3/library/time.html#time.perf_counter).