# `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.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).
Raw data
{
"_id": null,
"home_page": "https://github.com/mjmikulski/horology",
"name": "horology",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "timing, profiling, measure time, duration",
"author": "mjmikulski",
"author_email": "maciej.mikulski.jr@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/e9/1e/848e97d5a33229b1971342026304909f26112bca8072eb6cbf71d57c0698/horology-1.4.1.tar.gz",
"platform": null,
"description": "# `Horology`\n\n[](https://badge.fury.io/py/horology)\n[](https://github.com/mjmikulski/horology/actions/workflows/tests.yaml)\n[](https://github.com/mjmikulski/horology/actions/workflows/codeql.yaml)\n[](https://pypi.org/project/horology/)\n[](https://pypi.org/project/horology/)\n[](https://pepy.tech/project/horology)\n[](https://opensource.org/licenses/MIT)\n\n\nConveniently measures the time of your loops, contexts and functions.\n\n![](hourglass_blue.jpg \"Blue hourglass\")\n\n## Installation\n\n| horology version | compatible python |\n|------------------|-------------------|\n| 1.4.1 | 3.10-3.13 |\n| 1.4 | 3.10-3.12 |\n| 1.3 | 3.8-3.11 |\n| 1.2 | 3.6-3.9 |\n| 1.1 | 3.6-3.8 |\n\nHorology can be installed with PIP. It has no dependencies.\n\n```\npip install horology\n```\n\n## Usage\n\nThe following 3 tools will let you measure practically any part of your Python code.\n\n### Timing an iterable (list, tuple, generator, etc)\n\n#### Quick example\n\n```python\nfrom horology import Timed\n\nanimals = ['cat', 'dog', 'crocodile']\n\nfor x in Timed(animals):\n feed(x)\n```\n\nResult:\n\n```\niteration 1: 12.0 s\niteration 2: 8.00 s\niteration 3: 100 s\n\ntotal 3 iterations in 120 s\nmin/median/max: 8.00/12.0/100 s\naverage (std): 40.0 (52.0) s\n\n```\n\n#### Customization\n\nYou can specify where (if at all) you want each iteration and summary to be printed, eg.:\n\n```python\nfor x in Timed(animals, unit='ms',\n iteration_print_fn=logger.debug,\n summary_print_fn=logger.info):\n feed(x)\n```\n\n### Timing a function with a `@timed` decorator\n\n#### Quick example\n\n```python\nfrom horology import timed\n\n\n@timed\ndef foo():\n ...\n```\n\nResult:\n\n```\n>>> foo()\nfoo: 7.12 ms\n```\n\n#### Customization\n\nChose time unit and name:\n\n```python\n@timed(unit='s', name='Processing took ')\ndef bar():\n ...\n```\n\nResult:\n\n```\n>>> bar()\nProcessing took 0.185 s\n```\n\n### Timing part of code with a `Timing` context\n\n#### Quick example\n\nJust wrap your code using a `with` statement\n\n```python\nfrom horology import Timing\n\nwith Timing(name='Important calculations: '):\n ...\n```\n\nResult:\n\n```\nImportant calculations: 12.4 s\n```\n\n#### Customization\n\nYou can suppress default printing and directly use measured time (also within context)\n\n```python\nwith Timing(print_fn=None) as t:\n ...\n\nmake_use_of(t.interval)\n```\n\n## Time units\n\nTime units are by default automatically adjusted, for example you will see\n`foo: 7.12 ms` rather than `foo: 0.007 s`. If you don't like it, you can\noverride this by setting the `unit` argument with one of these names:\n`['ns', 'us', 'ms', 's', 'min', 'h', 'd']`.\n\n## Contributions\n\nContributions are welcomed, see [contribution guide](.github/contributing.md).\n\n## Internals\n\nHorology internally measures time with `perf_counter` which provides the *highest available resolution,*\nsee [docs](https://docs.python.org/3/library/time.html#time.perf_counter).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Conveniently measures the time of loops, contexts and functions.",
"version": "1.4.1",
"project_urls": {
"Homepage": "https://github.com/mjmikulski/horology",
"Repository": "https://github.com/mjmikulski/horology"
},
"split_keywords": [
"timing",
" profiling",
" measure time",
" duration"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cdc0036f30c82f3ed37799a3a51714098570dc6793f55612f22773c284703f8e",
"md5": "96bf3828d3919d93a26b8acd9bb69e85",
"sha256": "9fd6e35906c29f7c172ec134624ea89672a9b7aa80ffa7cda6708aa43279966f"
},
"downloads": -1,
"filename": "horology-1.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "96bf3828d3919d93a26b8acd9bb69e85",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 9576,
"upload_time": "2024-10-17T20:42:00",
"upload_time_iso_8601": "2024-10-17T20:42:00.070104Z",
"url": "https://files.pythonhosted.org/packages/cd/c0/036f30c82f3ed37799a3a51714098570dc6793f55612f22773c284703f8e/horology-1.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e91e848e97d5a33229b1971342026304909f26112bca8072eb6cbf71d57c0698",
"md5": "f7474f5233a0e4504b33d5ddb8e21b81",
"sha256": "530a628c4943bd16f0f09b14365cf03f36b56a9c8de3102f1e8b573afb88dce1"
},
"downloads": -1,
"filename": "horology-1.4.1.tar.gz",
"has_sig": false,
"md5_digest": "f7474f5233a0e4504b33d5ddb8e21b81",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 7365,
"upload_time": "2024-10-17T20:42:02",
"upload_time_iso_8601": "2024-10-17T20:42:02.068858Z",
"url": "https://files.pythonhosted.org/packages/e9/1e/848e97d5a33229b1971342026304909f26112bca8072eb6cbf71d57c0698/horology-1.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-17 20:42:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mjmikulski",
"github_project": "horology",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "horology"
}
JSON
