[](https://pepy.tech/project/metronomes)
[](https://pepy.tech/project/metronomes)
[](https://codecov.io/gh/pomponchik/metronomes)
[](https://github.com/boyter/scc/)
[](https://hitsofcode.com/github/pomponchik/metronomes/view?branch=main)
[](https://github.com/pomponchik/metronomes/actions/workflows/tests_and_coverage.yml)
[](https://pypi.python.org/pypi/metronomes)
[](https://badge.fury.io/py/metronomes)
[](http://mypy-lang.org/)
[](https://github.com/astral-sh/ruff)
This library offers the easiest way to run regular tasks. Just give it a function and tell it how many seconds you need to run it, then step back and don't interfere. For all its simplicity, there are:
- 📜 Logging the start and end of each operation.
- 🛡️ Error escaping. But not when you don't even know about the errors, but again - with detailed logging.
- ⇆ Thread safety.
- ❌ Support for [cancellation tokens](https://github.com/pomponchik/cantok).
## Table of contents
- [**Quick start**](#quick-start)
- [**Why?**](#why)
- [**Basic usage**](#basic-usage)
- [**Use it as a context manager**](#use-it-as-a-context-manager)
- [**Logging**](#logging)
- [**Error escaping**](#error-escaping)
- [**Working with Cancellation Tokens**](#working-with-cancellation-tokens)
- [**How to set a time limit**](#how-to-set-a-time-limit)
## Quick start
Install it:
```bash
pip install metronomes
```
And use:
```python
from time import sleep
from metronomes import Metronome
metronome = Metronome(0.2, lambda: print('go!'))
metronome.start()
sleep(1)
metronome.stop()
#> go!
#> go!
#> go!
#> go!
#> go!
```
You can also quickly try out this and other packages without having to install using [instld](https://github.com/pomponchik/instld).
## Why?
A [metronome](https://en.wikipedia.org/wiki/Metronome) is a special device that musicians often use. It looks something like this (if you are interested in how it works, I recommend watching the [video on YouTube](https://youtu.be/LvBEyyuVu60?si=NtaNSw0Xsv5ZPEKr)):
Its task is to produce sounds regularly and monotonously, which is very convenient if you want to develop a sense of rhythm. Unlike a person for whom strict rhythmicity is unusual, the metronome counts down time very accurately and therefore is used as a "guide" to which other rhythmic actions that we want to do are attached, whether it's tapping on a drum or pressing keys.
When we write programs, we also sometimes want some action to be performed regularly. And sometimes it happens that it may take a different amount of time, but we need the next action to start on time. This is exactly the task this library solves. When you call the `start()` method on a metronome object, it starts calling the function you passed once in a certain period of time. This happens in a separate specially created thread, so you can use these function calls to orchestrate some other actions in the main thread or even in several different threads.
At the same time, it may be important to you that even if in some cases the function does not work well and raises exceptions, in general the metronome continues to work, and after a certain time it will try to call this function again, and will not break at the first exception. After all, it would be strange if your real metronome went silent when you made a mistake in the rhythm that you are tapping on the drum, right? You may also want the errors that have occurred not to be lost, but to be recorded in your log. This library also provides all these amenities.
## Basic usage
The metronome object has 2 main methods: `start()` and `stop()`. Calling the `start()` method starts an additional thread, inside which the passed function starts running regularly in the loop. At the same time, the main thread can continue and, when it's necessary, stop the metronome calling the `stop()` method. Often, a metronome can be used for background notifications that are called during the execution of other code:
```python
from metronomes import Metronome
metronome = Metronome(0.001, lambda: print('An another function in progress...'))
metronome.start()
another_function()
metronome.stop()
#> An another function in progress...
#> An another function in progress...
#> An another function in progress...
```
Instead of manually starting and stopping the metronome, you can also use the [context manager mode](#use-it-as-a-context-manager).
The metronome object from this library cannot be used twice. If you started it once and then stopped it, you can't do it again:
```python
metronome = Metronome(0.2, lambda: print('go!'))
metronome.start()
sleep(0.2)
metronome.stop()
#> go!
metronome.start()
#> ...
#> metronomes.errors.RunStoppedMetronomeError: Metronomes are disposable, you cannot restart a stopped metronome.
```
## Use it as a context manager
We recommend using a metronome exclusively in the context manager mode, without "manual" start and stop:
```python
from time import sleep
from metronomes import Metronome
with Metronome(0.2, lambda: print('go!')):
sleep(1)
#> go!
#> go!
#> go!
#> go!
#> go!
```
In this case, it is guaranteed that the metronome will be completed correctly after the end of the code block and will not remain "hanging" in a separate thread. Even if an error occurs in the block.
## Logging
In order for events inside the metronome to start logging, you need to pass the logger object there:
```python
import logging
from time import sleep
from metronomes import Metronome
logging.basicConfig(
level=logging.DEBUG,
format="%(asctime)s [%(levelname)s] %(message)s",
handlers=[
logging.StreamHandler(),
]
)
logger = logging.getLogger('logger_name')
metronome = Metronome(0.2, lambda: print('go!'), logger=logger)
metronome.start()
sleep(1)
metronome.stop()
#> 2024-04-18 19:38:42,910 [INFO] The metronome starts...
#> 2024-04-18 19:38:42,910 [DEBUG] The beginning of the execution of callback "<lambda>".
#> go!
#> 2024-04-18 19:38:42,910 [DEBUG] Callback "<lambda>" has been successfully completed.
#> 2024-04-18 19:38:43,115 [DEBUG] The beginning of the execution of callback "<lambda>".
#> go!
#> 2024-04-18 19:38:43,116 [DEBUG] Callback "<lambda>" has been successfully completed.
#> 2024-04-18 19:38:43,321 [DEBUG] The beginning of the execution of callback "<lambda>".
#> go!
#> 2024-04-18 19:38:43,322 [DEBUG] Callback "<lambda>" has been successfully completed.
#> 2024-04-18 19:38:43,523 [DEBUG] The beginning of the execution of callback "<lambda>".
#> go!
#> 2024-04-18 19:38:43,524 [DEBUG] Callback "<lambda>" has been successfully completed.
#> 2024-04-18 19:38:43,727 [DEBUG] The beginning of the execution of callback "<lambda>".
#> go!
#> 2024-04-18 19:38:43,729 [DEBUG] Callback "<lambda>" has been successfully completed.
#> 2024-04-18 19:38:43,933 [INFO] The metronome has stopped.
```
The events of the start and stop of the metronome will be logged with the `INFO` level, start and stop of the passed function - `DEBUG`. If the operation time of the passed function was longer than the allotted time for one iteration, you will see a `WARNING` message.
And finally, if an exception is raised inside the function, it will be suppressed, and an `ERROR` level message will be recorded along with it (with the traceback saved, that is, the `exception()` method will be called for this from the logger):
```python
# Here should be some imports, logging settings, and the creation of a logger object
def function():
return 1/0
metronome = Metronome(0.2, function, logger=logger)
metronome.start()
sleep(0.4)
metronome.stop()
#> 2024-04-18 19:58:10,847 [INFO] The metronome starts...
#> 2024-04-18 19:58:10,847 [DEBUG] The beginning of the execution of callback "function".
#> 2024-04-18 19:58:10,847 [ERROR] The "ZeroDivisionError" ("division by zero") exception was suppressed inside the context.
#> Traceback (most recent call last):
#> File "/project_path/metronomes/metronomes/metronome.py", line 68, in run_loop
#> self.callback()
#> File "test.py", line ?, in function
#> return 1/0
#> ZeroDivisionError: division by zero
#> 2024-04-18 19:58:11,053 [DEBUG] The beginning of the execution of callback "function".
#> 2024-04-18 19:58:11,054 [ERROR] The "ZeroDivisionError" ("division by zero") exception was suppressed inside the context.
#> Traceback (most recent call last):
#> File "/project_path/metronomes/metronomes/metronome.py", line 68, in run_loop
#> self.callback()
#> File "test.py", line ?, in function
#> return 1/0
#> ZeroDivisionError: division by zero
#> 2024-04-18 19:58:11,258 [INFO] The metronome has stopped.
```
## Error escaping
Exceptions inside the function that you pass to the metronome will be:
- Suppressed.
- [Logged](#logging) (if you pass the logger object).
This applies to all the usual exceptions that are expected in normal code. For more information about the types of exceptions that are suppressed by default, read the documentation for the [`escaping`](https://github.com/pomponchik/escaping) library that is used for this.
## Working with Cancellation Tokens
This library is fully compatible with the [cancellation token pattern](https://cantok.readthedocs.io/en/latest/the_pattern/) and supports any token objects from the [`cantok`](https://github.com/pomponchik/cantok) library.
The essence of the pattern is that you can pass an object to metronome object, from which it can find out whether the work of the metronome still needs to be continued or not. If not, the metronome stops.
The token object is passed to the metronome as the `token` argument:
```python
from time import sleep
from metronomes import Metronome
from cantok import TimeoutToken
metronome = Metronome(0.2, lambda: None, token=TimeoutToken(1))
metronome.start()
print(metronome.stopped)
#> False
sleep(1.5) # Here I specify a little more time than in the constructor of the token itself, since a small margin is needed for operations related to the creation of the metronome object itself.
print(metronome.stopped)
#> True
```
You can also pass a token when calling the `start()` method:
```python
metronome.start(token=TimeoutToken(1))
```
If you pass cancellation tokens both during metronome initialization and in the `start()` method, their limitations will be summed up.
## How to set a time limit
You can specify a time limit (in seconds) for which the metronome will tick. When the specified time is over, it will simply stop. There are 2 ways to do this: when creating a metronome object or when calling the `start()` method.
In the first way, the time will start counting from the moment the metronome object is created:
```python
metronome = Metronome(0.2, lambda: print('go!'), duration=0.6)
metronome.start()
sleep(1)
#> go!
#> go!
#> go!
```
In the second way, the countdown will start by calling the `start()` method:
```python
metronome = Metronome(0.2, lambda: print('go!'))
metronome.start(duration=0.6)
sleep(1)
#> go!
#> go!
#> go!
```
Choose the right way to limit time. When using the metronome in the [context manager mode](#use-it-as-a-context-manager), only the first way is available to you, in almost all other situations - the second one is preferable.
Raw data
{
"_id": null,
"home_page": null,
"name": "metronomes",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "metronome, task scheduling, callbacks runner",
"author": null,
"author_email": "Evgeniy Blinov <zheni-b@yandex.ru>",
"download_url": "https://files.pythonhosted.org/packages/45/af/91e92fd2b2fcafd112760e904946f7660cc142f515e3235fed4303edfe22/metronomes-0.0.10.tar.gz",
"platform": null,
"description": "\n\n[](https://pepy.tech/project/metronomes)\n[](https://pepy.tech/project/metronomes)\n[](https://codecov.io/gh/pomponchik/metronomes)\n[](https://github.com/boyter/scc/)\n[](https://hitsofcode.com/github/pomponchik/metronomes/view?branch=main)\n[](https://github.com/pomponchik/metronomes/actions/workflows/tests_and_coverage.yml)\n[](https://pypi.python.org/pypi/metronomes)\n[](https://badge.fury.io/py/metronomes)\n[](http://mypy-lang.org/)\n[](https://github.com/astral-sh/ruff)\n\nThis library offers the easiest way to run regular tasks. Just give it a function and tell it how many seconds you need to run it, then step back and don't interfere. For all its simplicity, there are:\n\n- \ud83d\udcdc Logging the start and end of each operation.\n- \ud83d\udee1\ufe0f Error escaping. But not when you don't even know about the errors, but again - with detailed logging.\n- \u21c6 Thread safety.\n- \u274c Support for [cancellation tokens](https://github.com/pomponchik/cantok).\n\n\n## Table of contents\n\n- [**Quick start**](#quick-start)\n- [**Why?**](#why)\n- [**Basic usage**](#basic-usage)\n- [**Use it as a context manager**](#use-it-as-a-context-manager)\n- [**Logging**](#logging)\n- [**Error escaping**](#error-escaping)\n- [**Working with Cancellation Tokens**](#working-with-cancellation-tokens)\n- [**How to set a time limit**](#how-to-set-a-time-limit)\n\n\n## Quick start\n\nInstall it:\n\n```bash\npip install metronomes\n```\n\nAnd use:\n\n```python\nfrom time import sleep\nfrom metronomes import Metronome\n\nmetronome = Metronome(0.2, lambda: print('go!'))\n\nmetronome.start()\nsleep(1)\nmetronome.stop()\n#> go!\n#> go!\n#> go!\n#> go!\n#> go!\n```\n\nYou can also quickly try out this and other packages without having to install using [instld](https://github.com/pomponchik/instld).\n\n\n## Why?\n\nA [metronome](https://en.wikipedia.org/wiki/Metronome) is a special device that musicians often use. It looks something like this (if you are interested in how it works, I recommend watching the [video on YouTube](https://youtu.be/LvBEyyuVu60?si=NtaNSw0Xsv5ZPEKr)):\n\n\n\nIts task is to produce sounds regularly and monotonously, which is very convenient if you want to develop a sense of rhythm. Unlike a person for whom strict rhythmicity is unusual, the metronome counts down time very accurately and therefore is used as a \"guide\" to which other rhythmic actions that we want to do are attached, whether it's tapping on a drum or pressing keys.\n\nWhen we write programs, we also sometimes want some action to be performed regularly. And sometimes it happens that it may take a different amount of time, but we need the next action to start on time. This is exactly the task this library solves. When you call the `start()` method on a metronome object, it starts calling the function you passed once in a certain period of time. This happens in a separate specially created thread, so you can use these function calls to orchestrate some other actions in the main thread or even in several different threads.\n\nAt the same time, it may be important to you that even if in some cases the function does not work well and raises exceptions, in general the metronome continues to work, and after a certain time it will try to call this function again, and will not break at the first exception. After all, it would be strange if your real metronome went silent when you made a mistake in the rhythm that you are tapping on the drum, right? You may also want the errors that have occurred not to be lost, but to be recorded in your log. This library also provides all these amenities.\n\n\n## Basic usage\n\nThe metronome object has 2 main methods: `start()` and `stop()`. Calling the `start()` method starts an additional thread, inside which the passed function starts running regularly in the loop. At the same time, the main thread can continue and, when it's necessary, stop the metronome calling the `stop()` method. Often, a metronome can be used for background notifications that are called during the execution of other code:\n\n```python\nfrom metronomes import Metronome\n\nmetronome = Metronome(0.001, lambda: print('An another function in progress...'))\n\nmetronome.start()\nanother_function()\nmetronome.stop()\n#> An another function in progress...\n#> An another function in progress...\n#> An another function in progress...\n```\n\nInstead of manually starting and stopping the metronome, you can also use the [context manager mode](#use-it-as-a-context-manager).\n\nThe metronome object from this library cannot be used twice. If you started it once and then stopped it, you can't do it again:\n\n```python\nmetronome = Metronome(0.2, lambda: print('go!'))\n\nmetronome.start()\nsleep(0.2)\nmetronome.stop()\n#> go!\nmetronome.start()\n#> ...\n#> metronomes.errors.RunStoppedMetronomeError: Metronomes are disposable, you cannot restart a stopped metronome.\n```\n\n\n## Use it as a context manager\n\nWe recommend using a metronome exclusively in the context manager mode, without \"manual\" start and stop:\n\n```python\nfrom time import sleep\nfrom metronomes import Metronome\n\nwith Metronome(0.2, lambda: print('go!')):\n sleep(1)\n#> go!\n#> go!\n#> go!\n#> go!\n#> go!\n```\n\nIn this case, it is guaranteed that the metronome will be completed correctly after the end of the code block and will not remain \"hanging\" in a separate thread. Even if an error occurs in the block.\n\n\n## Logging\n\nIn order for events inside the metronome to start logging, you need to pass the logger object there:\n\n```python\nimport logging\nfrom time import sleep\nfrom metronomes import Metronome\n\nlogging.basicConfig(\n level=logging.DEBUG,\n format=\"%(asctime)s [%(levelname)s] %(message)s\",\n handlers=[\n logging.StreamHandler(),\n ]\n)\n\nlogger = logging.getLogger('logger_name')\nmetronome = Metronome(0.2, lambda: print('go!'), logger=logger)\n\nmetronome.start()\nsleep(1)\nmetronome.stop()\n#> 2024-04-18 19:38:42,910 [INFO] The metronome starts...\n#> 2024-04-18 19:38:42,910 [DEBUG] The beginning of the execution of callback \"<lambda>\".\n#> go!\n#> 2024-04-18 19:38:42,910 [DEBUG] Callback \"<lambda>\" has been successfully completed.\n#> 2024-04-18 19:38:43,115 [DEBUG] The beginning of the execution of callback \"<lambda>\".\n#> go!\n#> 2024-04-18 19:38:43,116 [DEBUG] Callback \"<lambda>\" has been successfully completed.\n#> 2024-04-18 19:38:43,321 [DEBUG] The beginning of the execution of callback \"<lambda>\".\n#> go!\n#> 2024-04-18 19:38:43,322 [DEBUG] Callback \"<lambda>\" has been successfully completed.\n#> 2024-04-18 19:38:43,523 [DEBUG] The beginning of the execution of callback \"<lambda>\".\n#> go!\n#> 2024-04-18 19:38:43,524 [DEBUG] Callback \"<lambda>\" has been successfully completed.\n#> 2024-04-18 19:38:43,727 [DEBUG] The beginning of the execution of callback \"<lambda>\".\n#> go!\n#> 2024-04-18 19:38:43,729 [DEBUG] Callback \"<lambda>\" has been successfully completed.\n#> 2024-04-18 19:38:43,933 [INFO] The metronome has stopped.\n```\n\nThe events of the start and stop of the metronome will be logged with the `INFO` level, start and stop of the passed function - `DEBUG`. If the operation time of the passed function was longer than the allotted time for one iteration, you will see a `WARNING` message.\n\nAnd finally, if an exception is raised inside the function, it will be suppressed, and an `ERROR` level message will be recorded along with it (with the traceback saved, that is, the `exception()` method will be called for this from the logger):\n\n```python\n# Here should be some imports, logging settings, and the creation of a logger object\n\ndef function():\n return 1/0\n\nmetronome = Metronome(0.2, function, logger=logger)\n\nmetronome.start()\nsleep(0.4)\nmetronome.stop()\n#> 2024-04-18 19:58:10,847 [INFO] The metronome starts...\n#> 2024-04-18 19:58:10,847 [DEBUG] The beginning of the execution of callback \"function\".\n#> 2024-04-18 19:58:10,847 [ERROR] The \"ZeroDivisionError\" (\"division by zero\") exception was suppressed inside the context.\n#> Traceback (most recent call last):\n#> File \"/project_path/metronomes/metronomes/metronome.py\", line 68, in run_loop\n#> self.callback()\n#> File \"test.py\", line ?, in function\n#> return 1/0\n#> ZeroDivisionError: division by zero\n#> 2024-04-18 19:58:11,053 [DEBUG] The beginning of the execution of callback \"function\".\n#> 2024-04-18 19:58:11,054 [ERROR] The \"ZeroDivisionError\" (\"division by zero\") exception was suppressed inside the context.\n#> Traceback (most recent call last):\n#> File \"/project_path/metronomes/metronomes/metronome.py\", line 68, in run_loop\n#> self.callback()\n#> File \"test.py\", line ?, in function\n#> return 1/0\n#> ZeroDivisionError: division by zero\n#> 2024-04-18 19:58:11,258 [INFO] The metronome has stopped.\n```\n\n\n## Error escaping\n\nExceptions inside the function that you pass to the metronome will be:\n\n- Suppressed.\n- [Logged](#logging) (if you pass the logger object).\n\nThis applies to all the usual exceptions that are expected in normal code. For more information about the types of exceptions that are suppressed by default, read the documentation for the [`escaping`](https://github.com/pomponchik/escaping) library that is used for this.\n\n\n## Working with Cancellation Tokens\n\nThis library is fully compatible with the [cancellation token pattern](https://cantok.readthedocs.io/en/latest/the_pattern/) and supports any token objects from the [`cantok`](https://github.com/pomponchik/cantok) library.\n\nThe essence of the pattern is that you can pass an object to metronome object, from which it can find out whether the work of the metronome still needs to be continued or not. If not, the metronome stops.\n\nThe token object is passed to the metronome as the `token` argument:\n\n```python\nfrom time import sleep\nfrom metronomes import Metronome\nfrom cantok import TimeoutToken\n\nmetronome = Metronome(0.2, lambda: None, token=TimeoutToken(1))\n\nmetronome.start()\nprint(metronome.stopped)\n#> False\nsleep(1.5) # Here I specify a little more time than in the constructor of the token itself, since a small margin is needed for operations related to the creation of the metronome object itself.\nprint(metronome.stopped)\n#> True\n```\n\nYou can also pass a token when calling the `start()` method:\n\n```python\nmetronome.start(token=TimeoutToken(1))\n```\n\nIf you pass cancellation tokens both during metronome initialization and in the `start()` method, their limitations will be summed up.\n\n\n## How to set a time limit\n\nYou can specify a time limit (in seconds) for which the metronome will tick. When the specified time is over, it will simply stop. There are 2 ways to do this: when creating a metronome object or when calling the `start()` method.\n\nIn the first way, the time will start counting from the moment the metronome object is created:\n\n```python\nmetronome = Metronome(0.2, lambda: print('go!'), duration=0.6) \n\nmetronome.start()\nsleep(1)\n#> go!\n#> go!\n#> go!\n```\n\nIn the second way, the countdown will start by calling the `start()` method:\n\n```python\nmetronome = Metronome(0.2, lambda: print('go!')) \n\nmetronome.start(duration=0.6)\nsleep(1)\n#> go!\n#> go!\n#> go!\n```\n\nChoose the right way to limit time. When using the metronome in the [context manager mode](#use-it-as-a-context-manager), only the first way is available to you, in almost all other situations - the second one is preferable.\n",
"bugtrack_url": null,
"license": null,
"summary": "Endless tick-tock generators",
"version": "0.0.10",
"project_urls": {
"Source": "https://github.com/pomponchik/metronomes",
"Tracker": "https://github.com/pomponchik/metronomes/issues"
},
"split_keywords": [
"metronome",
" task scheduling",
" callbacks runner"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0d26a00ff4796257619415ee6dfa04d06953a557c99742ab29520c74b7e50114",
"md5": "4e28f19940a589ab08be4c0e2167c549",
"sha256": "691ebbcf67ec7cd0ecf7a2e160a8393094666922eb9d2ae775d16ced7acc5396"
},
"downloads": -1,
"filename": "metronomes-0.0.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4e28f19940a589ab08be4c0e2167c549",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 8595,
"upload_time": "2024-07-23T13:27:17",
"upload_time_iso_8601": "2024-07-23T13:27:17.363301Z",
"url": "https://files.pythonhosted.org/packages/0d/26/a00ff4796257619415ee6dfa04d06953a557c99742ab29520c74b7e50114/metronomes-0.0.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "45af91e92fd2b2fcafd112760e904946f7660cc142f515e3235fed4303edfe22",
"md5": "bd55d52439946afd585f02665ff09624",
"sha256": "131864ab1f8a45e108af25504b5ed9a7100679afe36d62ae1bf62a72d855bf8c"
},
"downloads": -1,
"filename": "metronomes-0.0.10.tar.gz",
"has_sig": false,
"md5_digest": "bd55d52439946afd585f02665ff09624",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 8547,
"upload_time": "2024-07-23T13:27:18",
"upload_time_iso_8601": "2024-07-23T13:27:18.677236Z",
"url": "https://files.pythonhosted.org/packages/45/af/91e92fd2b2fcafd112760e904946f7660cc142f515e3235fed4303edfe22/metronomes-0.0.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-23 13:27:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pomponchik",
"github_project": "metronomes",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "metronomes"
}
JSON
