| Name | harami JSON |
| Version |
0.0.9
JSON |
| download |
| home_page | None |
| Summary | A lightweight 'Event' and 'Observable' library. |
| upload_time | 2025-08-12 04:46:42 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.12 |
| license | None |
| keywords |
event
eventhandler
observable
observer
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
`harami` (ハラミ) is a lightweight "Event" and "Observable" library for Python.
This README is only a high-level introduction to **harami**. For more detailed documentation, please view the official docs at [https://harami.readthedocs.io](https://harami.readthedocs.io).
## Installation
**harami** can be installed from pypi through the usual means:
```bash
pip install harami
```
## Usage
Let's try a "learn by example" approach. The following code is a Widget Factory implementation. The Widget Factory raises an event on Widget Creation, it also emits the Widgets it creates through an Observable. The MyApp class creates an instance of the Widget Factory, adds an event handler, adds an observer, and finally requests the factory create a Widget.
```python
from harami import *
class Widget:
color:str
def __init__(self, color:str = None) -> None:
self.color = color
class WidgetEventArgs(EventArgs):
@property
def widget(self) -> Widget:
return self.args[0]
class WidgetFactory:
def __init__(self) -> None:
self.widgetEmitter = Observable[Widget]()
@event(WidgetEventArgs)
def onWidgetCreated(self, widget:Widget) -> None:
# this is an "Event Source", it does not require an
# implementation, but one can be provided if it
# makes sense for your application
pass
def createWidget(color:str) -> None:
widget = Widget(color)
self.onWidgetCreated(widget)
self.widgetEmitter(widget)
class MyApp:
def __init__(self) -> None:
self.__widgetFactory = WidgetFactory()
self.__widgetFactory.onWidgetCreated += self.__onWidgetCreatedHandler
self.__widgetFactory.widgetEmitter += self.__widgetObserver
def __onWidgetCreatedHandler(sender:object, e:WidgetEventArgs) -> None:
print(f'Widget Created: color is {e.widget.color}')
def __widgetObserver(widget:Widget) -> None:
print(f'Widget Emitted: color is {e.widget.color}')
def run(self) -> None:
self.__widgetFactory.createWidget('red')
MyApp().run()
```
When executed the program outputs the following:
```plaintext
Widget Created: color is red
Widget Emitted: color is red
```
## Notables..
Things not obvious given the example above:
* Events and Observables can be declared at a module scope (classes are not required.)
* There are no visibility restrictions (public vs. private) for events/observables nor handlers/observers.
* Event Handlers can be async, whether or not the Event Source is async.
* Event Sources can be async, whether or not Event Handlers are async.
* Event Handlers receive an EventArgs, which you can optionally subclass as seen in the example.
* All `*args` and `**kwargs` passed to an Event Source are forwarded via an `args` attribute of type `tuple` and a `kwargs` attribute of type `dict`, both accessible via `EventArgs`.
* An Event Source does not need to be parameterized, in such cases `EventArgs.empty` will be forwarded.
* An `EventArgs` subclass does not need to be specified via `@event` (it defaults to `EventArgs`).
* Observers can be async, even though observables do not expose an async/coro signature.
* Observables provide a value-assignment syntax, ex: `myObserver.state = 'foo'`, this may help simplify using observables to back properties.
* Events offer `addHandler()`/`removeHandler()`, and observables offer `attach()`/`detach()`, each as alternatives to `+=`/`-=` syntax as seen in the example.
* Last, but not least, Observables can be used as Event Handlers, and Event Sources can be used as Observers.
This library is meant to be lightweight and not have dependencies on other libraries, as such it has an intentionally narrow focus.
## Contact
You can reach me on [Discord](https://discordapp.com/users/307684202080501761) or [open an Issue on Github](https://github.com/wilson0x4d/harami/issues/new/choose).
Raw data
{
"_id": null,
"home_page": null,
"name": "harami",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "event, eventhandler, observable, observer",
"author": null,
"author_email": "Shaun Wilson <mrshaunwilson@msn.com>",
"download_url": "https://files.pythonhosted.org/packages/5d/7f/ad127bcee3cb4d8da05d3798fcd5ea8c360348762ffb0f0ff431ea1d23d0/harami-0.0.9.tar.gz",
"platform": null,
"description": "`harami` (\u30cf\u30e9\u30df) is a lightweight \"Event\" and \"Observable\" library for Python.\n\nThis README is only a high-level introduction to **harami**. For more detailed documentation, please view the official docs at [https://harami.readthedocs.io](https://harami.readthedocs.io).\n\n## Installation\n\n**harami** can be installed from pypi through the usual means:\n\n```bash\npip install harami\n```\n\n## Usage\n\nLet's try a \"learn by example\" approach. The following code is a Widget Factory implementation. The Widget Factory raises an event on Widget Creation, it also emits the Widgets it creates through an Observable. The MyApp class creates an instance of the Widget Factory, adds an event handler, adds an observer, and finally requests the factory create a Widget.\n\n```python\nfrom harami import *\n\nclass Widget:\n color:str\n def __init__(self, color:str = None) -> None:\n self.color = color\n\nclass WidgetEventArgs(EventArgs):\n @property\n def widget(self) -> Widget:\n return self.args[0]\n\nclass WidgetFactory:\n def __init__(self) -> None:\n self.widgetEmitter = Observable[Widget]()\n\n @event(WidgetEventArgs)\n def onWidgetCreated(self, widget:Widget) -> None:\n # this is an \"Event Source\", it does not require an\n # implementation, but one can be provided if it\n # makes sense for your application\n pass\n\n def createWidget(color:str) -> None:\n widget = Widget(color)\n self.onWidgetCreated(widget)\n self.widgetEmitter(widget)\n\nclass MyApp:\n def __init__(self) -> None:\n self.__widgetFactory = WidgetFactory()\n self.__widgetFactory.onWidgetCreated += self.__onWidgetCreatedHandler\n self.__widgetFactory.widgetEmitter += self.__widgetObserver\n\n def __onWidgetCreatedHandler(sender:object, e:WidgetEventArgs) -> None:\n print(f'Widget Created: color is {e.widget.color}')\n\n def __widgetObserver(widget:Widget) -> None:\n print(f'Widget Emitted: color is {e.widget.color}')\n\n def run(self) -> None:\n self.__widgetFactory.createWidget('red')\n\nMyApp().run()\n```\n\nWhen executed the program outputs the following:\n\n```plaintext\nWidget Created: color is red\nWidget Emitted: color is red\n```\n\n## Notables..\n\nThings not obvious given the example above:\n\n* Events and Observables can be declared at a module scope (classes are not required.)\n* There are no visibility restrictions (public vs. private) for events/observables nor handlers/observers.\n* Event Handlers can be async, whether or not the Event Source is async.\n* Event Sources can be async, whether or not Event Handlers are async.\n* Event Handlers receive an EventArgs, which you can optionally subclass as seen in the example.\n* All `*args` and `**kwargs` passed to an Event Source are forwarded via an `args` attribute of type `tuple` and a `kwargs` attribute of type `dict`, both accessible via `EventArgs`.\n* An Event Source does not need to be parameterized, in such cases `EventArgs.empty` will be forwarded.\n* An `EventArgs` subclass does not need to be specified via `@event` (it defaults to `EventArgs`).\n* Observers can be async, even though observables do not expose an async/coro signature.\n* Observables provide a value-assignment syntax, ex: `myObserver.state = 'foo'`, this may help simplify using observables to back properties.\n* Events offer `addHandler()`/`removeHandler()`, and observables offer `attach()`/`detach()`, each as alternatives to `+=`/`-=` syntax as seen in the example.\n* Last, but not least, Observables can be used as Event Handlers, and Event Sources can be used as Observers.\n\nThis library is meant to be lightweight and not have dependencies on other libraries, as such it has an intentionally narrow focus.\n\n## Contact\n\nYou can reach me on [Discord](https://discordapp.com/users/307684202080501761) or [open an Issue on Github](https://github.com/wilson0x4d/harami/issues/new/choose).\n",
"bugtrack_url": null,
"license": null,
"summary": "A lightweight 'Event' and 'Observable' library.",
"version": "0.0.9",
"project_urls": {
"Documentation": "https://harami.readthedocs.io/",
"Homepage": "https://github.com/wilson0x4d/harami",
"Repository": "https://github.com/wilson0x4d/harami.git"
},
"split_keywords": [
"event",
" eventhandler",
" observable",
" observer"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "73009ae36f36629c329a67657b28f58eccc4d20216b0f4fb995d6f974af5be21",
"md5": "5d2d134c0f3be7aa8926a8aed527f6b9",
"sha256": "7470b193451cbb08e16ff2804aabaf2eed5df13bef82683b4a3dd0ac414c7c22"
},
"downloads": -1,
"filename": "harami-0.0.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5d2d134c0f3be7aa8926a8aed527f6b9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 7491,
"upload_time": "2025-08-12T04:46:41",
"upload_time_iso_8601": "2025-08-12T04:46:41.362869Z",
"url": "https://files.pythonhosted.org/packages/73/00/9ae36f36629c329a67657b28f58eccc4d20216b0f4fb995d6f974af5be21/harami-0.0.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5d7fad127bcee3cb4d8da05d3798fcd5ea8c360348762ffb0f0ff431ea1d23d0",
"md5": "ee76bf0bd1145b722dbf126d335059eb",
"sha256": "178b45619283cb7c14cc4ff3bbc3a87b22c5195c3f743a70001c9019b7d1a140"
},
"downloads": -1,
"filename": "harami-0.0.9.tar.gz",
"has_sig": false,
"md5_digest": "ee76bf0bd1145b722dbf126d335059eb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 6253,
"upload_time": "2025-08-12T04:46:42",
"upload_time_iso_8601": "2025-08-12T04:46:42.479893Z",
"url": "https://files.pythonhosted.org/packages/5d/7f/ad127bcee3cb4d8da05d3798fcd5ea8c360348762ffb0f0ff431ea1d23d0/harami-0.0.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-12 04:46:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "wilson0x4d",
"github_project": "harami",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "harami"
}
