# `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)
Conveniently measures the time of your loops, contexts and functions.
## Installation
| horology version | compatible python |
|------------------|-------------------|
| 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": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "timing,profiling,measure time,duration",
"author": "mjmikulski",
"author_email": "maciej.mikulski.jr@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/cb/4a/77bd1e977ca2b15584f756164e448476d417b2c3c544a2a495210eba0376/horology-1.3.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\nConveniently measures the time of your loops, contexts and functions.\n\n![](hourglass.jpg \"Photo by Mike from Pexels\")\n\n## Installation\n\n| horology version | compatible python |\n|------------------|-------------------|\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.3.1",
"split_keywords": [
"timing",
"profiling",
"measure time",
"duration"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "179adaa8314185c1e1b4f6916f68ee087a156768a39d7884c4278ed00ed53f7a",
"md5": "a06c5212fb9a597321e4dc6f851ab5cf",
"sha256": "8a651a7400803012e6ed70ee66141a1ee2939dc59f5b510605f81a58744f1654"
},
"downloads": -1,
"filename": "horology-1.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a06c5212fb9a597321e4dc6f851ab5cf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 9286,
"upload_time": "2023-01-04T11:37:08",
"upload_time_iso_8601": "2023-01-04T11:37:08.409023Z",
"url": "https://files.pythonhosted.org/packages/17/9a/daa8314185c1e1b4f6916f68ee087a156768a39d7884c4278ed00ed53f7a/horology-1.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cb4a77bd1e977ca2b15584f756164e448476d417b2c3c544a2a495210eba0376",
"md5": "0f524945f5538a36668217e083fbbe27",
"sha256": "b609d94ce15832897e7876ce30d311049b0e794e96eddb239369a1ddc4d64c73"
},
"downloads": -1,
"filename": "horology-1.3.1.tar.gz",
"has_sig": false,
"md5_digest": "0f524945f5538a36668217e083fbbe27",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 7834,
"upload_time": "2023-01-04T11:37:09",
"upload_time_iso_8601": "2023-01-04T11:37:09.644282Z",
"url": "https://files.pythonhosted.org/packages/cb/4a/77bd1e977ca2b15584f756164e448476d417b2c3c544a2a495210eba0376/horology-1.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-04 11:37:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "mjmikulski",
"github_project": "horology",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "horology"
}
JSON
