# TimerContext
Context Manager for timing blocks of python code simply.
## Installation
Install TimerContext using pip, uv, or another package manager by downloading from PyPI.
```bash
pip install timer-context
```
```bash
uv pip install timer-context
```
## Usage
`TimerContext` is a context manager, and will time code used within a `with` block.
```python
import time
def func(x):
time.sleep(x)
with TimerContext() as timer:
func(3)
timer.duration # duration will be approximately 3 seconds
func(2)
timer.duration # duration will be approximately 5 seconds
func(1)
timer.duration # duration will be approximately 6 seconds
print(timer.start)
print(timer.end)
print(timer.duration) # duration will be approximately 6 seconds
```
Any code inside of the context manager will contribute to the duration. As soon as the context is left, the timer will stop counting.
## API Reference
`TimerContext` has four attributes intended to be used by the user, `start`, `end`, `duration`, and `duration_ns`.
- `start` is simply a `datetime.datetime` object representing (approximately) when the context started.
- `end` is simply a `datetime.datetime` object representing (approximately) when the context ended.
- `duration` is a property representing the number of milliseconds of the duration of the timer (as a float). If the context is still ongoing, it will report the number of milliseconds since the timer context until duration was called. If the context is closed, then it will report the number of milliseconds the context was open.
- `duration_ns` is a property representing the number of nanoseconds of the duration of the timer (as an int).
## Notice on Resolution
The duration is always calculated using `time.perf_counter_ns` and then converted to milliseconds as a float. The precision of this timer is limited by the resolution of the performance counter on your particular environment.
The precision is also limited by the overhead of calling a context manager. If your context is exceptionally fast (on the order of single nanoseconds), this overhead is non-negligible, and you would be better served by calling `time.perf_counter_ns` directly. For any block that runs for longer than that, the overhead is proportionally small/negligible.
Because the counter used for duration is set after defining `timer.start` and before defining `timer.end`, `timer.duration` might not exactly equal `timer.end-timer.start`, generally. The times used for `start` and `end` are lower resolution than the performance counter for the duration. Thus, they should generally only be used for reference, and not for calculating a duration.
## Comparison with `timeit` and `cProfile`.
Timing/profiling Python code is generally done with the [`timeit`](https://docs.python.org/3/library/timeit.html) and/or [`cProfile`](https://docs.python.org/3/library/profile.html) modules in the standard library. These are both great tools, and may be better suited for your task.
You should use `timeit` if:
- You need statistics on runtime by running an identical code snippet many times.
You should use `cProfile` if:
- You need more detailed reports on the runtime of individual lines/function calls. ([`cProfile.Profile`](https://docs.python.org/3/library/profile.html#profile.Profile) can also conveniently be used as a context manager!)
You should use `TimerContext` if:
- You need to only time a block of code once without interrupting its flow.
- You do not need detailed profiling reports
- Rewriting your block of code as a function would be inconvenient.
- You want an incredibly simple interface for timing code.
## Contributing
Please open an Issue if you find a bug or would like to request a feature. Bugs are generally fixed promptly. Because of `TimerContext`'s goal of being a radically simple interface, complex feature requests will likely be closed, but genuine improvements that do not sacrifice the vision of simplicity may be considered. We recommend opening an issue to discuss new features before opening a Pull Request. Pull Requests for bug fixes are always welcome.
Raw data
{
"_id": null,
"home_page": null,
"name": "timer-context",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "timing, performance, context-manager, python",
"author": null,
"author_email": "Andrew Sansom <andrew@euleriancircuit.com>",
"download_url": "https://files.pythonhosted.org/packages/d0/4f/bb7d9b09ff45df2b81a45095c0a5b73cfe58d56973b84af4e9284f67be0d/timer_context-1.1.1.tar.gz",
"platform": null,
"description": "# TimerContext\nContext Manager for timing blocks of python code simply.\n\n## Installation\n\nInstall TimerContext using pip, uv, or another package manager by downloading from PyPI.\n\n```bash\npip install timer-context\n```\n\n```bash\nuv pip install timer-context\n```\n\n## Usage\n\n`TimerContext` is a context manager, and will time code used within a `with` block.\n\n```python\nimport time\n\n\ndef func(x):\n time.sleep(x)\n\nwith TimerContext() as timer:\n func(3)\n timer.duration # duration will be approximately 3 seconds\n func(2)\n timer.duration # duration will be approximately 5 seconds\n func(1)\n timer.duration # duration will be approximately 6 seconds\n\nprint(timer.start)\nprint(timer.end)\nprint(timer.duration) # duration will be approximately 6 seconds\n```\n\nAny code inside of the context manager will contribute to the duration. As soon as the context is left, the timer will stop counting.\n\n## API Reference\n\n`TimerContext` has four attributes intended to be used by the user, `start`, `end`, `duration`, and `duration_ns`.\n\n- `start` is simply a `datetime.datetime` object representing (approximately) when the context started.\n- `end` is simply a `datetime.datetime` object representing (approximately) when the context ended.\n- `duration` is a property representing the number of milliseconds of the duration of the timer (as a float). If the context is still ongoing, it will report the number of milliseconds since the timer context until duration was called. If the context is closed, then it will report the number of milliseconds the context was open.\n- `duration_ns` is a property representing the number of nanoseconds of the duration of the timer (as an int).\n\n## Notice on Resolution\n\nThe duration is always calculated using `time.perf_counter_ns` and then converted to milliseconds as a float. The precision of this timer is limited by the resolution of the performance counter on your particular environment.\n\nThe precision is also limited by the overhead of calling a context manager. If your context is exceptionally fast (on the order of single nanoseconds), this overhead is non-negligible, and you would be better served by calling `time.perf_counter_ns` directly. For any block that runs for longer than that, the overhead is proportionally small/negligible.\n\nBecause the counter used for duration is set after defining `timer.start` and before defining `timer.end`, `timer.duration` might not exactly equal `timer.end-timer.start`, generally. The times used for `start` and `end` are lower resolution than the performance counter for the duration. Thus, they should generally only be used for reference, and not for calculating a duration.\n\n## Comparison with `timeit` and `cProfile`.\n\nTiming/profiling Python code is generally done with the [`timeit`](https://docs.python.org/3/library/timeit.html) and/or [`cProfile`](https://docs.python.org/3/library/profile.html) modules in the standard library. These are both great tools, and may be better suited for your task.\n\nYou should use `timeit` if:\n- You need statistics on runtime by running an identical code snippet many times.\n\nYou should use `cProfile` if:\n- You need more detailed reports on the runtime of individual lines/function calls. ([`cProfile.Profile`](https://docs.python.org/3/library/profile.html#profile.Profile) can also conveniently be used as a context manager!)\n\nYou should use `TimerContext` if:\n- You need to only time a block of code once without interrupting its flow.\n- You do not need detailed profiling reports\n- Rewriting your block of code as a function would be inconvenient.\n- You want an incredibly simple interface for timing code.\n\n## Contributing\n\nPlease open an Issue if you find a bug or would like to request a feature. Bugs are generally fixed promptly. Because of `TimerContext`'s goal of being a radically simple interface, complex feature requests will likely be closed, but genuine improvements that do not sacrifice the vision of simplicity may be considered. We recommend opening an issue to discuss new features before opening a Pull Request. Pull Requests for bug fixes are always welcome.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A simple context manager for timing blocks of Python code.",
"version": "1.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/qthequartermasterman/timer-context/issues",
"Homepage": "https://github.com/qthequartermasterman/timer-context"
},
"split_keywords": [
"timing",
" performance",
" context-manager",
" python"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "db5d71c378d1ce5ab5abec88effb2b5d2c8abb56799eb07a5b83a2fdc024eee4",
"md5": "b660cd68979ea6815080363ca1836268",
"sha256": "f8d014a897fa9c6b9c55c713ec04a1561b8314621357a389d90950afa742e104"
},
"downloads": -1,
"filename": "timer_context-1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b660cd68979ea6815080363ca1836268",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 5138,
"upload_time": "2025-02-14T19:02:24",
"upload_time_iso_8601": "2025-02-14T19:02:24.496420Z",
"url": "https://files.pythonhosted.org/packages/db/5d/71c378d1ce5ab5abec88effb2b5d2c8abb56799eb07a5b83a2fdc024eee4/timer_context-1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d04fbb7d9b09ff45df2b81a45095c0a5b73cfe58d56973b84af4e9284f67be0d",
"md5": "bd9656ebe0f9d8a8a52e3c623993393b",
"sha256": "8a1863e52cc768c2008ee0f2353c39ea5cbdaf46f6a2ea747551c4efc8e04336"
},
"downloads": -1,
"filename": "timer_context-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "bd9656ebe0f9d8a8a52e3c623993393b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 6158,
"upload_time": "2025-02-14T19:02:26",
"upload_time_iso_8601": "2025-02-14T19:02:26.503134Z",
"url": "https://files.pythonhosted.org/packages/d0/4f/bb7d9b09ff45df2b81a45095c0a5b73cfe58d56973b84af4e9284f67be0d/timer_context-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-14 19:02:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "qthequartermasterman",
"github_project": "timer-context",
"github_not_found": true,
"lcname": "timer-context"
}
JSON
