*This library is currently being beta-tested. See something that's broken? Did we get something
wrong? [Create an issue and let us know!][issues]*
<p align="center">
<a id="superloops" href="#superloops">
<img src="https://github.com/Voyz/superloops/blob/master/media/superloops_logotype_A01.png" alt="SuperLoops logo" title="SuperLoops logo" width="400"/>
</a>
</p>
<p align="center">
<a href="https://opensource.org/licenses/Apache-2.0">
<img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg"/>
</a>
<a href="https://github.com/Voyz/superloops/releases">
<img src="https://img.shields.io/pypi/v/superloops?label=version"/>
</a>
</p>
```posh
pip install superloops
```
SuperLoops package simplifies and augments usage of Python threads.
Features:
* Startup, shutdown, hard reset
* Thread events
* Co-dependant thread health propagation
* 0 dependencies
* 100% automated test coverage
```python
class ProcessLoop(SuperLoop):
def cycle(self):
# process stuff in a separate thread
loop = ProcessLoop()
loop.start()
# ProcessLoop_0: Started
loop.stop()
# ProcessLoop_0: Exited gracefully
loop.hard_reset() # when nothing else helps 😬
```
Thread events?
```python
class ApiFeedLoop(SuperLoop):
def on_start(self):
self.api = Api(key=my_key)
def on_stop(self):
self.api.disconnect()
def cycle(self):
self.api.get_feed()
# on_thread_start, on_thread_stop...
```
Multiple threads that need to stay healthy?
```python
loop_controller = LoopController()
process_loop = loop_controller.new_loop(ProcessLoop())
api_feed_loop = loop_controller.new_loop(ApiFeedLoop())
loop_controller.start()
# LoopController_0: Started
loop_controller.maintain_loops()
# ProcessLoop_0: Started
# ApiFeedLoop_0: Started
api_feed_loop.failure() # oops!
# LoopController_0: Stopping loops.
# ProcessLoop_0: Exited gracefully
# ApiFeedLoop_0: Exited gracefully
# LoopController_0: Restarting loops.
# ProcessLoop_1: Started
# ApiFeedLoop_1: Started
```
In summary, SuperLoops provide support for thread maintenance, events, failure handling, health status propagation, and graceful termination.
## <a name="how-superloops-works"></a>How does SuperLoops work?
SuperLoop is a class that wraps around a Python `threading.Thread` object. It exposes an interface for thread starting, stopping, hard restarts, graceful termination and events: `on_start`, `on_stop`, `on_thread_start` and `on_thread_stop`.
Each time you restart a SuperLoop, it will create a new Thread, handling naming and graceful termination for you.
Aided by the LoopController class, the SuperLoops are able to communicate their health between each other. This ensures that should one SuperLoop fail and need restarting, all other connected SuperLoops would be restarted too.
## Documentation
To use a SuperLoop, declare a class inheriting from SuperLoop and extend the `cycle` method
```python
from superloops import SuperLoop
class MyLoop(SuperLoop):
def cycle(self):
pass
# process stuff
loop = MyLoop()
```
You can use the following methods of SuperLoop to control the thread lifecycle.
```python
loop.start()
loop.stop()
loop.hard_reset()
loop.failure()
```
#### `start()`
Start a new thread (unless one is already started) that will be used to operate the loop. This will start calling the overridden `cycle()` method indefinitely on the new thread. Any arguments passed to this method will be passed to the `on_start` callback.
#### `stop()`
Stop the existing thread (unless there isn't one started) and join the thread, waiting up to the amount of seconds specified by the `grace_period` argument of this class. Any arguments passed to this method will be passed to the `on_stop` callback.
#### `hard_reset()`
Stop the thread by calling `stop()` method and mark it as killed, attempting to gracefully finish as soon as the control is returned from the `cycle()` method. Independently of whether the current thread stops gracefully, a new thread will be instantly started.
#### `failure()`
Indicate that there has been a critical failure in the operation of the thread. If the amount of failures exceeds `max_loop_failures` specified as the argument of this class, the thread will stop and (if provided) unset its GreenLight.
That indicates that the health status should be propagated across other threads managed through the LoopController that this loop belongs to, and that all specified threads should be restarted.
#### SuperLoop arguments
* `green_light` (`threading.Event`): A `threading.Event` object representing the health state of the loop. It gets set automatically when a loop is added to LoopController.
* `grace_period` (`int`): The number of seconds to wait when stopping the loop gracefully. Default is 5 seconds.
* `max_loop_failures` (`int`): The maximum number of failures allowed before reporting issues. Default is 10 failures.
* `stop_on_failure` (`bool`): A flag that indicates if this loop should be stopped when it exceeds its `max_loop_failures`. Default is `False`.
* `reset_globally` (`bool`): A flag that indicates if this loop should be reset when other loops report issues. Default is `True`.
### Events
SuperLoop provides lifecycle event callbacks that facilitate flexibility in managing the loop and its thread.
#### on_start
The `on_start` callback is invoked before a new thread is created and started. It can be used to perform any setup that is required before the loop starts running.
This method must return a boolean indicating whether the loop should continue starting.
#### on_stop
The `on_stop` callback is invoked after the loop's thread is stopped. This method can be used to perform any cleanup that is required after the loop has stopped running.
#### on_thread_start
The `on_thread_start` callback is invoked from within the loop's thread before the loop starts running. This method can be used to perform any setup that must be done within the context of the loop's thread.
#### on_thread_stop
The `on_thread_stop` callback is invoked from within the loop's thread after the loop has stopped running. This method can be used to perform any cleanup that must be done within the context of the loop's thread.
Example:
```python
def thread_name():
return threading.current_thread().name
class MyLoop(SuperLoop):
def on_start(self):
print(f'on_start - {thread_name()}')
# Perform any necessary setup here
return True # Return False to prevent the loop from starting
def on_stop(self):
print(f'on_stop - {thread_name()}')
# Perform any necessary cleanup here
def on_thread_start(self):
print(f'on_thread_start - {thread_name()}')
# Perform any necessary setup here
def on_thread_stop(self):
print(f'on_thread_stop - {thread_name()}')
# Perform any necessary cleanup here
def cycle(self):
pass
loop = MyLoop()
loop.start()
# on_start - MainThread
# on_thread_start - MyLoop_0
loop.stop()
# on_stop - MainThread
# on_thread_stop - MyLoop_0
```
### Loop Controller
SuperLoops are built with the intent of being able to link multiple threads into a single co-dependant system. If one thread in such system fails, all threads can be restarted allowing for an easy way to ensure multiple sub-systems can recover from a failure.
This is executed by adding various SuperLoops to a LoopController class, calling the `LoopController.new_loop()` method, passing the SuperLoop as the argument.
LoopController needs to be started, which will launch a separate thread observing for the health status of all the threads.
```python
loop_controller = LoopController()
process_loop = loop_controller.new_loop(ProcessLoop())
api_feed_loop = loop_controller.new_loop(ApiFeedLoop())
loop_controller.start()
```
For convenience, LoopController can also ensure that all its SuperLoops are started, by calling `maintain_loops`, or stopped by calling `stop_loops`.
```python
loop_controller.maintain_loops()
loop_controller.stop_loops()
```
#### LoopController arguments
* `reset_callback` (`callable`): A callable to be executed when the `LoopController` resets loops.
* `green_light` (`threading.Event`): A `threading.Event` that will be used to control the health status of the loops. Creates one if not provided.
## Examples
See [Usage examples](https://github.com/Voyz/superloops/tree/master/bin/examples) for more.
## Licence
See [LICENSE](https://github.com/Voyz/superloops/blob/master/LICENSE)
## Disclaimer
SuperLoops is provided on an AS IS and AS AVAILABLE basis without any representation or endorsement made and without warranty of any kind whether express or implied, including but not limited to the implied warranties of satisfactory quality, fitness for a particular purpose, non-infringement, compatibility, security and accuracy. To the extent permitted by law, SuperLoops' authors will not be liable for any indirect or consequential loss or damage whatever (including without limitation loss of business, opportunity, data, profits) arising out of or in connection with the use of SuperLoops. SuperLoops' authors make no warranty that the functionality of SuperLoops will be uninterrupted or error free, that defects will be corrected or that SuperLoops or the server that makes it available are free of viruses or anything else which may be harmful
or destructive.
## Built by Voy
Hi! Thanks for checking out and using this library. If you are interested in discussing your project, require
mentorship, consider hiring me, or just wanna chat - I'm happy to talk.
You can send me an email to get in touch: hello@voyzan.com
Or if you'd just want to give something back, I've got a Buy Me A Coffee account:
<a href="https://www.buymeacoffee.com/voyzan" rel="nofollow">
<img src="https://raw.githubusercontent.com/Voyz/voyz_public/master/vz_BMC.png" alt="Buy Me A Coffee" style="max-width:100%;" width="192">
</a>
Thanks and have an awesome day 👋
[issues]: https://github.com/Voyz/superloops/issues
Raw data
{
"_id": null,
"home_page": "https://github.com/Voyz/superloops",
"name": "superloops",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "thread,threads,python threads,threading,multithreading,asynchronous,concurrency,thread management",
"author": "Voy Zan",
"author_email": "voy1982@yahoo.co.uk",
"download_url": "https://files.pythonhosted.org/packages/4c/b8/7f16301c2824448ae0a8e18a075ff5f92fd73ebc726075b4eb98b3aa179a/superloops-0.1.3.tar.gz",
"platform": null,
"description": "*This library is currently being beta-tested. See something that's broken? Did we get something\r\nwrong? [Create an issue and let us know!][issues]*\r\n\r\n<p align=\"center\">\r\n <a id=\"superloops\" href=\"#superloops\">\r\n <img src=\"https://github.com/Voyz/superloops/blob/master/media/superloops_logotype_A01.png\" alt=\"SuperLoops logo\" title=\"SuperLoops logo\" width=\"400\"/>\r\n </a>\r\n</p>\r\n\r\n<p align=\"center\">\r\n <a href=\"https://opensource.org/licenses/Apache-2.0\">\r\n <img src=\"https://img.shields.io/badge/License-Apache%202.0-blue.svg\"/> \r\n </a>\r\n <a href=\"https://github.com/Voyz/superloops/releases\">\r\n <img src=\"https://img.shields.io/pypi/v/superloops?label=version\"/> \r\n </a>\r\n</p>\r\n\r\n```posh\r\npip install superloops\r\n```\r\n\r\n\r\nSuperLoops package simplifies and augments usage of Python threads.\r\n\r\nFeatures:\r\n\r\n* Startup, shutdown, hard reset\r\n* Thread events\r\n* Co-dependant thread health propagation\r\n* 0 dependencies\r\n* 100% automated test coverage\r\n\r\n```python\r\nclass ProcessLoop(SuperLoop):\r\n def cycle(self):\r\n # process stuff in a separate thread\r\n\r\nloop = ProcessLoop()\r\nloop.start()\r\n# ProcessLoop_0: Started \r\n\r\nloop.stop()\r\n# ProcessLoop_0: Exited gracefully\r\n\r\nloop.hard_reset() # when nothing else helps \u00f0\u0178\u02dc\u00ac \r\n```\r\n\r\nThread events?\r\n\r\n```python\r\nclass ApiFeedLoop(SuperLoop):\r\n def on_start(self):\r\n self.api = Api(key=my_key)\r\n \r\n def on_stop(self):\r\n self.api.disconnect()\r\n \r\n def cycle(self):\r\n self.api.get_feed()\r\n\r\n # on_thread_start, on_thread_stop...\r\n```\r\n\r\nMultiple threads that need to stay healthy?\r\n\r\n```python\r\nloop_controller = LoopController()\r\n\r\nprocess_loop = loop_controller.new_loop(ProcessLoop())\r\napi_feed_loop = loop_controller.new_loop(ApiFeedLoop())\r\n\r\nloop_controller.start()\r\n# LoopController_0: Started\r\n\r\nloop_controller.maintain_loops()\r\n# ProcessLoop_0: Started\r\n# ApiFeedLoop_0: Started\r\n\r\napi_feed_loop.failure() # oops!\r\n\r\n# LoopController_0: Stopping loops.\r\n# ProcessLoop_0: Exited gracefully\r\n# ApiFeedLoop_0: Exited gracefully\r\n\r\n# LoopController_0: Restarting loops.\r\n# ProcessLoop_1: Started\r\n# ApiFeedLoop_1: Started\r\n```\r\n\r\n\r\nIn summary, SuperLoops provide support for thread maintenance, events, failure handling, health status propagation, and graceful termination.\r\n\r\n\r\n## <a name=\"how-superloops-works\"></a>How does SuperLoops work?\r\n\r\nSuperLoop is a class that wraps around a Python `threading.Thread` object. It exposes an interface for thread starting, stopping, hard restarts, graceful termination and events: `on_start`, `on_stop`, `on_thread_start` and `on_thread_stop`.\r\n\r\nEach time you restart a SuperLoop, it will create a new Thread, handling naming and graceful termination for you.\r\n\r\nAided by the LoopController class, the SuperLoops are able to communicate their health between each other. This ensures that should one SuperLoop fail and need restarting, all other connected SuperLoops would be restarted too.\r\n\r\n## Documentation \r\n\r\n\r\nTo use a SuperLoop, declare a class inheriting from SuperLoop and extend the `cycle` method\r\n```python\r\nfrom superloops import SuperLoop\r\n\r\nclass MyLoop(SuperLoop):\r\n def cycle(self):\r\n pass\r\n # process stuff\r\n\r\nloop = MyLoop()\r\n```\r\n\r\nYou can use the following methods of SuperLoop to control the thread lifecycle.\r\n\r\n```python\r\nloop.start()\r\nloop.stop()\r\nloop.hard_reset()\r\nloop.failure()\r\n```\r\n\r\n#### `start()`\r\nStart a new thread (unless one is already started) that will be used to operate the loop. This will start calling the overridden `cycle()` method indefinitely on the new thread. Any arguments passed to this method will be passed to the `on_start` callback.\r\n\r\n#### `stop()`\r\nStop the existing thread (unless there isn't one started) and join the thread, waiting up to the amount of seconds specified by the `grace_period` argument of this class. Any arguments passed to this method will be passed to the `on_stop` callback.\r\n\r\n#### `hard_reset()`\r\nStop the thread by calling `stop()` method and mark it as killed, attempting to gracefully finish as soon as the control is returned from the `cycle()` method. Independently of whether the current thread stops gracefully, a new thread will be instantly started.\r\n\r\n#### `failure()`\r\nIndicate that there has been a critical failure in the operation of the thread. If the amount of failures exceeds `max_loop_failures` specified as the argument of this class, the thread will stop and (if provided) unset its GreenLight. \r\n\r\nThat indicates that the health status should be propagated across other threads managed through the LoopController that this loop belongs to, and that all specified threads should be restarted.\r\n\r\n#### SuperLoop arguments\r\n\r\n* `green_light` (`threading.Event`): A `threading.Event` object representing the health state of the loop. It gets set automatically when a loop is added to LoopController.\r\n* `grace_period` (`int`): The number of seconds to wait when stopping the loop gracefully. Default is 5 seconds.\r\n* `max_loop_failures` (`int`): The maximum number of failures allowed before reporting issues. Default is 10 failures.\r\n* `stop_on_failure` (`bool`): A flag that indicates if this loop should be stopped when it exceeds its `max_loop_failures`. Default is `False`.\r\n* `reset_globally` (`bool`): A flag that indicates if this loop should be reset when other loops report issues. Default is `True`.\r\n\r\n### Events\r\n\r\nSuperLoop provides lifecycle event callbacks that facilitate flexibility in managing the loop and its thread.\r\n\r\n#### on_start\r\n\r\nThe `on_start` callback is invoked before a new thread is created and started. It can be used to perform any setup that is required before the loop starts running.\r\n\r\nThis method must return a boolean indicating whether the loop should continue starting.\r\n\r\n\r\n#### on_stop\r\n\r\nThe `on_stop` callback is invoked after the loop's thread is stopped. This method can be used to perform any cleanup that is required after the loop has stopped running.\r\n\r\n#### on_thread_start\r\n\r\nThe `on_thread_start` callback is invoked from within the loop's thread before the loop starts running. This method can be used to perform any setup that must be done within the context of the loop's thread.\r\n\r\n#### on_thread_stop\r\n\r\nThe `on_thread_stop` callback is invoked from within the loop's thread after the loop has stopped running. This method can be used to perform any cleanup that must be done within the context of the loop's thread.\r\n\r\nExample:\r\n\r\n```python\r\ndef thread_name():\r\n return threading.current_thread().name\r\n\r\nclass MyLoop(SuperLoop):\r\n def on_start(self):\r\n print(f'on_start - {thread_name()}')\r\n # Perform any necessary setup here\r\n return True # Return False to prevent the loop from starting\r\n \r\n def on_stop(self):\r\n print(f'on_stop - {thread_name()}')\r\n # Perform any necessary cleanup here\r\n\r\n def on_thread_start(self):\r\n print(f'on_thread_start - {thread_name()}')\r\n # Perform any necessary setup here\r\n\r\n def on_thread_stop(self):\r\n print(f'on_thread_stop - {thread_name()}')\r\n # Perform any necessary cleanup here\r\n \r\n def cycle(self):\r\n pass\r\n\r\nloop = MyLoop()\r\n\r\nloop.start()\r\n# on_start - MainThread\r\n# on_thread_start - MyLoop_0\r\nloop.stop()\r\n# on_stop - MainThread\r\n# on_thread_stop - MyLoop_0\r\n```\r\n\r\n### Loop Controller\r\n\r\nSuperLoops are built with the intent of being able to link multiple threads into a single co-dependant system. If one thread in such system fails, all threads can be restarted allowing for an easy way to ensure multiple sub-systems can recover from a failure.\r\n\r\nThis is executed by adding various SuperLoops to a LoopController class, calling the `LoopController.new_loop()` method, passing the SuperLoop as the argument.\r\n\r\n\r\nLoopController needs to be started, which will launch a separate thread observing for the health status of all the threads.\r\n\r\n```python\r\nloop_controller = LoopController()\r\n\r\nprocess_loop = loop_controller.new_loop(ProcessLoop())\r\napi_feed_loop = loop_controller.new_loop(ApiFeedLoop())\r\n\r\nloop_controller.start()\r\n```\r\n\r\nFor convenience, LoopController can also ensure that all its SuperLoops are started, by calling `maintain_loops`, or stopped by calling `stop_loops`.\r\n\r\n```python\r\nloop_controller.maintain_loops()\r\nloop_controller.stop_loops()\r\n```\r\n\r\n#### LoopController arguments\r\n* `reset_callback` (`callable`): A callable to be executed when the `LoopController` resets loops.\r\n* `green_light` (`threading.Event`): A `threading.Event` that will be used to control the health status of the loops. Creates one if not provided.\r\n\r\n## Examples\r\n\r\nSee [Usage examples](https://github.com/Voyz/superloops/tree/master/bin/examples) for more.\r\n\r\n## Licence\r\n\r\nSee [LICENSE](https://github.com/Voyz/superloops/blob/master/LICENSE)\r\n\r\n## Disclaimer\r\n\r\nSuperLoops is provided on an AS IS and AS AVAILABLE basis without any representation or endorsement made and without warranty of any kind whether express or implied, including but not limited to the implied warranties of satisfactory quality, fitness for a particular purpose, non-infringement, compatibility, security and accuracy. To the extent permitted by law, SuperLoops' authors will not be liable for any indirect or consequential loss or damage whatever (including without limitation loss of business, opportunity, data, profits) arising out of or in connection with the use of SuperLoops. SuperLoops' authors make no warranty that the functionality of SuperLoops will be uninterrupted or error free, that defects will be corrected or that SuperLoops or the server that makes it available are free of viruses or anything else which may be harmful\r\nor destructive.\r\n\r\n\r\n## Built by Voy\r\n\r\nHi! Thanks for checking out and using this library. If you are interested in discussing your project, require\r\nmentorship, consider hiring me, or just wanna chat - I'm happy to talk.\r\n\r\nYou can send me an email to get in touch: hello@voyzan.com\r\n\r\nOr if you'd just want to give something back, I've got a Buy Me A Coffee account:\r\n\r\n<a href=\"https://www.buymeacoffee.com/voyzan\" rel=\"nofollow\">\r\n <img src=\"https://raw.githubusercontent.com/Voyz/voyz_public/master/vz_BMC.png\" alt=\"Buy Me A Coffee\" style=\"max-width:100%;\" width=\"192\">\r\n</a>\r\n\r\nThanks and have an awesome day \u00f0\u0178\u2018\u2039\r\n\r\n\r\n[issues]: https://github.com/Voyz/superloops/issues\r\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "SuperLoops package simplifies and augments usage of Python threads. It provides support for thread maintenance, events, failure handling, health status propagation, and graceful termination.",
"version": "0.1.3",
"project_urls": {
"Homepage": "https://github.com/Voyz/superloops"
},
"split_keywords": [
"thread",
"threads",
"python threads",
"threading",
"multithreading",
"asynchronous",
"concurrency",
"thread management"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4cb87f16301c2824448ae0a8e18a075ff5f92fd73ebc726075b4eb98b3aa179a",
"md5": "7bfda6c93f48744cd375de2e39c8ec7c",
"sha256": "3d9bfad801f39fec1f2b763e552778cda414e8073372406bdd4038483fb4c1f0"
},
"downloads": -1,
"filename": "superloops-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "7bfda6c93f48744cd375de2e39c8ec7c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 18715,
"upload_time": "2024-02-27T07:02:13",
"upload_time_iso_8601": "2024-02-27T07:02:13.865519Z",
"url": "https://files.pythonhosted.org/packages/4c/b8/7f16301c2824448ae0a8e18a075ff5f92fd73ebc726075b4eb98b3aa179a/superloops-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-27 07:02:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Voyz",
"github_project": "superloops",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "superloops"
}
JSON
