# EventSail
[](https://codecov.io/gh/satyamsoni2211/eventsail)    
EventSail is a minimal observer pattern package which is performant as well as supports both sync and async operations. Born out of utility and curiosity to replicate Javascript `EventEmitter`, here we are with library with similar functionalities.
## Usage
### Installation
Package can be installed from `PyPi` using below command.
```bash
python -m pip install eventsail
```
If using `poetry` or `pipenv` for packaging, use below command.
```bash
poetry add eventsail
pipenv install eventsail
```
### Info
`EventSail` has a very minimal configuration to get started. It exports `Event` class which consumes `Emitter` under the hood for firing callbacks for the events. For easing, creation of `Event`, `EventSail` also exports `event` method for instantiation.
```python
from eventsail import event, Event
test_event: Event = event('test_event_name')
```
Resultant `test_event` will be a synchronous event type. If you want an asynchronous event, you can instantiate it as.
```python
test_event: Event = event("test", is_sync=False)
```
Now test_event would be of type asynchronous event.
### Subscribing a callback
To register callbacks/handlers, you can either call subscribe method on `Event` instance passing callback/function or you can also use it as decorator over your method.
```python
def foo(*args,**kwargs): ...
test_event.subscribe(foo)
```
or
```python
@test_event.subscribe
def foo(*args,**kwargs): ...
```
> For Async event, all the callbacks will be delegated to threads thus preventing any operations to be blocked.
If you want to leverage power of `async/await` you will have to hint `Event` class to do so by passing `use_asyncio` flag to `True`.
```python
test_event = event("test", is_sync=False, use_asyncio=True)
```
This way it will entertain coroutines as well by creating `Task` and placing them over running event loop. For non coroutine methods, it will execute them over loop in a Thread Pool executor, thus preventing blocking of Event loop.
If you want to call a callback/listener only once, you can use `once` method exposed by `Event` object. Post trigger, listener will be automatically unsubscribed.
```python
@test_event.once
def foo(*args,**kwargs): ...
```
Above callback will only be fired once.
### Unsubscribing a callback
To unsubscribe a callback, you can simply call `unsubscribe` method on Object passing callback you want to unsubscribe.
```python
test_event.unsubscribe(abc)
```
> Calling this method on already unsubscribed callback would do no harm.
To remove all the listeners/callbacks, you can call clear method.
```python
test_event.clear()
```
`Event` class is also singleton class, so you will always get same instance for same set of arguments. This is intentionally kept in place so that we do not loose listeners subscribed.
### Waiting for async tasks
There can be instances where we would need to wait for async emitted tasks to complete before shutdown as this can be critical. `Event` class exposes certain properties containing `async` tasks.
- `Event.all_async_tasks` : This will return all the async tasks scheduled over Event loop for the Emitter.
- `Event.own_async_tasks` : This will only return async tasks corresponding to the immediate parent Emitter of the Event.
To wait for async tasks to complete, `Event` class exposes awaitable API to wait for tasks to complete. This can be called as below.
```python
await test_event.wait_for_async_tasks()
```
This will wait for all the async tasks. This also has a default timeout for 10 seconds post which it will error out.
## Testing
To run tests, simply run below command:
```bash
pytest -s --cov=.
```
## License
`EventSail` is released under the MIT License. See the bundled LICENSE file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/satyamsoni2211/eventsail",
"name": "eventsail",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "events, emitter, event-emitter, event-handling, event-listener, event-subscriber, event-publisher",
"author": "Satyam Soni",
"author_email": "satyam.soni@hotmail.co.uk",
"download_url": "https://files.pythonhosted.org/packages/1b/6d/06c46147dce450f784cd0d73712a97f1bfb0443c511a55bb22b983b26313/eventsail-0.1.2.tar.gz",
"platform": null,
"description": "# EventSail\n\n[](https://codecov.io/gh/satyamsoni2211/eventsail)    \n\nEventSail is a minimal observer pattern package which is performant as well as supports both sync and async operations. Born out of utility and curiosity to replicate Javascript `EventEmitter`, here we are with library with similar functionalities.\n\n\n\n## Usage\n\n### Installation\n\nPackage can be installed from `PyPi` using below command.\n\n```bash\npython -m pip install eventsail\n```\n\nIf using `poetry` or `pipenv` for packaging, use below command.\n\n```bash\npoetry add eventsail\npipenv install eventsail\n```\n\n### Info\n\n`EventSail` has a very minimal configuration to get started. It exports `Event` class which consumes `Emitter` under the hood for firing callbacks for the events. For easing, creation of `Event`, `EventSail` also exports `event` method for instantiation.\n\n```python\nfrom eventsail import event, Event\ntest_event: Event = event('test_event_name')\n```\n\nResultant `test_event` will be a synchronous event type. If you want an asynchronous event, you can instantiate it as.\n\n```python\ntest_event: Event = event(\"test\", is_sync=False)\n```\n\nNow test_event would be of type asynchronous event.\n\n### Subscribing a callback\n\nTo register callbacks/handlers, you can either call subscribe method on `Event` instance passing callback/function or you can also use it as decorator over your method.\n\n```python\ndef foo(*args,**kwargs): ...\ntest_event.subscribe(foo)\n```\n\nor\n\n```python\n@test_event.subscribe\ndef foo(*args,**kwargs): ...\n```\n\n> For Async event, all the callbacks will be delegated to threads thus preventing any operations to be blocked.\n\nIf you want to leverage power of `async/await` you will have to hint `Event` class to do so by passing `use_asyncio` flag to `True`.\n\n```python\ntest_event = event(\"test\", is_sync=False, use_asyncio=True)\n```\n\nThis way it will entertain coroutines as well by creating `Task` and placing them over running event loop. For non coroutine methods, it will execute them over loop in a Thread Pool executor, thus preventing blocking of Event loop.\n\nIf you want to call a callback/listener only once, you can use `once` method exposed by `Event` object. Post trigger, listener will be automatically unsubscribed.\n\n```python\n@test_event.once\ndef foo(*args,**kwargs): ...\n```\n\nAbove callback will only be fired once.\n\n### Unsubscribing a callback\n\nTo unsubscribe a callback, you can simply call `unsubscribe` method on Object passing callback you want to unsubscribe.\n\n```python\ntest_event.unsubscribe(abc)\n```\n\n> Calling this method on already unsubscribed callback would do no harm.\n\nTo remove all the listeners/callbacks, you can call clear method.\n\n```python\ntest_event.clear()\n```\n\n`Event` class is also singleton class, so you will always get same instance for same set of arguments. This is intentionally kept in place so that we do not loose listeners subscribed.\n\n### Waiting for async tasks\n\nThere can be instances where we would need to wait for async emitted tasks to complete before shutdown as this can be critical. `Event` class exposes certain properties containing `async` tasks.\n\n- `Event.all_async_tasks` : This will return all the async tasks scheduled over Event loop for the Emitter.\n- `Event.own_async_tasks` : This will only return async tasks corresponding to the immediate parent Emitter of the Event.\n\nTo wait for async tasks to complete, `Event` class exposes awaitable API to wait for tasks to complete. This can be called as below.\n\n```python\nawait test_event.wait_for_async_tasks()\n```\n\nThis will wait for all the async tasks. This also has a default timeout for 10 seconds post which it will error out.\n\n## Testing\n\nTo run tests, simply run below command:\n\n```bash\npytest -s --cov=.\n```\n\n## License\n\n`EventSail` is released under the MIT License. See the bundled LICENSE file for details.\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Library for emitting events and handling them in a decoupled way.",
"version": "0.1.2",
"project_urls": {
"Homepage": "https://github.com/satyamsoni2211/eventsail",
"Repository": "https://github.com/satyamsoni2211/eventsail"
},
"split_keywords": [
"events",
" emitter",
" event-emitter",
" event-handling",
" event-listener",
" event-subscriber",
" event-publisher"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b7ae958e7233a8f23605b3727d1b9fb23ffcdac9efcd38ff6eec5a7b930d7333",
"md5": "d118eae28f336be2cc8aa423469246e6",
"sha256": "e48c2ceffa837a0209c1a44d24018ca1c947f70653c9452ffecbce4dc2d16101"
},
"downloads": -1,
"filename": "eventsail-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d118eae28f336be2cc8aa423469246e6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 5213,
"upload_time": "2024-04-17T08:11:49",
"upload_time_iso_8601": "2024-04-17T08:11:49.328507Z",
"url": "https://files.pythonhosted.org/packages/b7/ae/958e7233a8f23605b3727d1b9fb23ffcdac9efcd38ff6eec5a7b930d7333/eventsail-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1b6d06c46147dce450f784cd0d73712a97f1bfb0443c511a55bb22b983b26313",
"md5": "ca74c1f3ed5fb079fd5b744ff023988b",
"sha256": "745b5724fd7a37cb433687046d5d023f471a7dfddb2aee7471cf809dd4f510ce"
},
"downloads": -1,
"filename": "eventsail-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "ca74c1f3ed5fb079fd5b744ff023988b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 4995,
"upload_time": "2024-04-17T08:11:50",
"upload_time_iso_8601": "2024-04-17T08:11:50.790217Z",
"url": "https://files.pythonhosted.org/packages/1b/6d/06c46147dce450f784cd0d73712a97f1bfb0443c511a55bb22b983b26313/eventsail-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-17 08:11:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "satyamsoni2211",
"github_project": "eventsail",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "eventsail"
}
JSON
