# What is this?
A simple event manager that works between processes
# How do I use this?
`pip install elegant_events`
file1.py
```python
from elegant_events import Server
# will spinup a server in the background if one isn't already running
server1 = Server("localhost", 7070)
#
# listener examples:
#
# attach a callback that triggers every time
@server1.whenever("found_an_event")
def when_event_found(timestamp, data):
print(f'''data = {data}''')
# attach a callback that will only trigger one time
@server1.once("something_started")
def when_event_found(timestamp, data):
print(f'''data = {data}''')
#
# send data example
#
server1.push(event_name="found_an_event", data="Hello from same process")
#
# receive/handle events examples
#
# option 1: manually check (e.g. the cooperative multitasking)
sleep(10) # (run the file2.py while this file is sleeping)
server1.check()
# because `.push()` was called twice, when_event_found() will be triggered twice right here
# option 1: auto-check; (highly responsive and efficient sleep-wait)
# behaves like (but is MUCH better than):
# while True: server1.check()
server1.listen_forever()
```
file2.py
```python
from elegant_events import Server
# will spinup a server in the background if one isn't already running
server1 = Server("localhost", 7070)
# "data" can be anything that works with json.dumps()
server1.push(event_name="found_an_event", data={"Hello from different process!": True})
```
# API Overview
```py
from elegant_events import Server
server1 = Server("localhost", 7070)
server1.yell(event_name, data)
# only already-started processes will hear this event
# its efficient but only use this if you know the listener will be up-and-running
server1.push(event_name, data, max_size=math.inf)
# similar to yell, BUT processes that start AFTER this function call
# (even 5min after) will *sometimes hear this event
# if max_size=Infinty
# processes WILL hear every push, no caveats
# if there are 5 pushes, then 10min later a
# process starts and has a whenever("name")
# that whenever-callback will immediately execute 5 times in a row
# if max_size=1
# processes will always hear the most-recent push event
# BUT will not know about any push events before then
# max_size can be any positive integer, as its the size of the buffer
# NOTE: there is only one max_size per event_name, meaning:
# push("blah_event", max_size=9)
# push("blah_event", max_size=9)
# push("blah_event", max_size=1)
# other_process.check() # <-- will only see ONE "blah_event"
# # because the push(max_size=1)
# # effectively wiped out the buffer
server1.keep_track_of(event_name, should_return_timestamp=False)
# This will start saving events, even there are no callbacks setup
# good to use this immediately after a server is started.
# Once a callback is attached, it will then have the history of the event-occurances
server1.stop_keeping_track_of(event_name, wipeout_backlog=True)
# if wipeout_backlog=True, no callbacks for event_name will trigger on the .check()
# if wipeout_backlog=False, callbacks can still trigger on the next .check()
# so long as the event itself (the .yell() or .push()) occured before the .stop_keeping_track_of()
server1.check(event_name=None, event_names=None)
# asks the server for all the relvent events that occured since the last .check()
# and then triggers the callbacks in chonological order
# by default it gets all events
# event_name="name" will save on bandwidth and only get those events
# event_names=["name1", "name2"] will save on bandwidth and only get those events
server1.locally_trigger(event_name, timestamp, data)
# rarely should this be needed, but if you want to "fake" that an event has occured
# this function will fake it without any interaction with the network
# (e.g. it won't tell any other processes)
server1.whenever(event_name, catch_and_print_errors=True)
# this attaches a callback function
# NOTE: "whenever" really means "whenever", including if the event happened in the past
# catch_and_print_errors=False
# RARELY will this ever be desireable
# .check() is when the callbacks are run
# so, when this is false, if the callback throws an error
# the .check() will also throw, and will NOT run ANY other
# callbacks for ANY EVENT (e.g. crashes)
# NOTE: the rare case where .whenever() is called two times on the same function
# the function will be called twice when the event happen
# (and will execute n times per event if .whenever() is called times)
server1.once(event_name, catch_and_print_errors=True)
# this also attaches a callback function, which will be detatched after it executes one time
# NOTE: this will execute event if the event happened before the callback was attached
# which is particularly useful when doing once("something_started")
# and the "something_started" event happened before this process started
# for catch_and_print_errors=False, see the .whenever() example above
server1.whenever_future(event_name, catch_and_print_errors=True)
# same as .whenever() but will only trigger for events that happen after this function is defined/attached
server1.once_next(event_name, catch_and_print_errors=True)
# same as .once() but will only trigger for events that happen after this function is defined/attached
server1.remove_callback(event_name, callback)
# NOTE: the rare case where the same callback is attached two times
# this remove will only remove the first callback
# For more fine-grained control manually edit the server1.callback_entries, ex:
# for callback_func, catch_and_print_errors, runs_once, time_threshold in server1.callback_entries[event_name]:
server1.listen_forever()
# this established a live connection with the server
# and any time any event occurs, the callback will immediately run for said event
# (no backlog/batching)
```
Raw data
{
"_id": null,
"home_page": "https://github.com/jeff-hykin/elegant_events",
"name": "elegant-events",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "",
"author": "Jeff Hykin",
"author_email": "jeff.hykin@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/3f/30/8ad5af2c3c8add3d8970439a75205df0d5ca36db70c282f08752c5f8a00f/elegant_events-0.1.0.tar.gz",
"platform": null,
"description": "# What is this?\n\nA simple event manager that works between processes\n\n# How do I use this?\n\n`pip install elegant_events`\n\nfile1.py\n\n```python\nfrom elegant_events import Server\n\n# will spinup a server in the background if one isn't already running\nserver1 = Server(\"localhost\", 7070)\n\n# \n# listener examples:\n# \n\n# attach a callback that triggers every time\n@server1.whenever(\"found_an_event\")\ndef when_event_found(timestamp, data):\n print(f'''data = {data}''')\n\n# attach a callback that will only trigger one time\n@server1.once(\"something_started\")\ndef when_event_found(timestamp, data):\n print(f'''data = {data}''')\n\n# \n# send data example\n# \nserver1.push(event_name=\"found_an_event\", data=\"Hello from same process\")\n\n\n# \n# receive/handle events examples\n# \n\n# option 1: manually check (e.g. the cooperative multitasking)\nsleep(10) # (run the file2.py while this file is sleeping)\nserver1.check()\n# because `.push()` was called twice, when_event_found() will be triggered twice right here\n\n# option 1: auto-check; (highly responsive and efficient sleep-wait)\n# behaves like (but is MUCH better than):\n# while True: server1.check()\nserver1.listen_forever()\n```\n\n\nfile2.py\n\n```python\nfrom elegant_events import Server\n\n# will spinup a server in the background if one isn't already running\nserver1 = Server(\"localhost\", 7070)\n\n# \"data\" can be anything that works with json.dumps()\nserver1.push(event_name=\"found_an_event\", data={\"Hello from different process!\": True})\n```\n\n# API Overview\n\n```py\nfrom elegant_events import Server\nserver1 = Server(\"localhost\", 7070)\n\nserver1.yell(event_name, data)\n# only already-started processes will hear this event\n# its efficient but only use this if you know the listener will be up-and-running\n\nserver1.push(event_name, data, max_size=math.inf)\n# similar to yell, BUT processes that start AFTER this function call\n# (even 5min after) will *sometimes hear this event\n# if max_size=Infinty\n# processes WILL hear every push, no caveats\n# if there are 5 pushes, then 10min later a \n# process starts and has a whenever(\"name\")\n# that whenever-callback will immediately execute 5 times in a row\n# if max_size=1\n# processes will always hear the most-recent push event\n# BUT will not know about any push events before then\n# max_size can be any positive integer, as its the size of the buffer\n# NOTE: there is only one max_size per event_name, meaning:\n# push(\"blah_event\", max_size=9)\n# push(\"blah_event\", max_size=9)\n# push(\"blah_event\", max_size=1) \n# other_process.check() # <-- will only see ONE \"blah_event\" \n# # because the push(max_size=1)\n# # effectively wiped out the buffer\n\nserver1.keep_track_of(event_name, should_return_timestamp=False)\n# This will start saving events, even there are no callbacks setup\n# good to use this immediately after a server is started.\n# Once a callback is attached, it will then have the history of the event-occurances\n\nserver1.stop_keeping_track_of(event_name, wipeout_backlog=True)\n# if wipeout_backlog=True, no callbacks for event_name will trigger on the .check()\n# if wipeout_backlog=False, callbacks can still trigger on the next .check()\n# so long as the event itself (the .yell() or .push()) occured before the .stop_keeping_track_of()\n\nserver1.check(event_name=None, event_names=None)\n# asks the server for all the relvent events that occured since the last .check()\n# and then triggers the callbacks in chonological order\n# by default it gets all events\n# event_name=\"name\" will save on bandwidth and only get those events\n# event_names=[\"name1\", \"name2\"] will save on bandwidth and only get those events\n\nserver1.locally_trigger(event_name, timestamp, data)\n# rarely should this be needed, but if you want to \"fake\" that an event has occured\n# this function will fake it without any interaction with the network\n# (e.g. it won't tell any other processes)\n\nserver1.whenever(event_name, catch_and_print_errors=True)\n# this attaches a callback function\n# NOTE: \"whenever\" really means \"whenever\", including if the event happened in the past\n# catch_and_print_errors=False\n# RARELY will this ever be desireable\n# .check() is when the callbacks are run\n# so, when this is false, if the callback throws an error\n# the .check() will also throw, and will NOT run ANY other\n# callbacks for ANY EVENT (e.g. crashes)\n# NOTE: the rare case where .whenever() is called two times on the same function\n# the function will be called twice when the event happen\n# (and will execute n times per event if .whenever() is called times)\n\nserver1.once(event_name, catch_and_print_errors=True)\n# this also attaches a callback function, which will be detatched after it executes one time\n# NOTE: this will execute event if the event happened before the callback was attached\n# which is particularly useful when doing once(\"something_started\") \n# and the \"something_started\" event happened before this process started\n# for catch_and_print_errors=False, see the .whenever() example above\n\nserver1.whenever_future(event_name, catch_and_print_errors=True)\n# same as .whenever() but will only trigger for events that happen after this function is defined/attached\n\nserver1.once_next(event_name, catch_and_print_errors=True)\n# same as .once() but will only trigger for events that happen after this function is defined/attached\n\nserver1.remove_callback(event_name, callback)\n# NOTE: the rare case where the same callback is attached two times\n# this remove will only remove the first callback\n# For more fine-grained control manually edit the server1.callback_entries, ex:\n# for callback_func, catch_and_print_errors, runs_once, time_threshold in server1.callback_entries[event_name]:\n\nserver1.listen_forever()\n# this established a live connection with the server \n# and any time any event occurs, the callback will immediately run for said event\n# (no backlog/batching)\n```\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Easily send data and events between processes, or within a single process",
"version": "0.1.0",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8a00a8a8ba5bc5f00be322680760167024721cf63487b07aef70b72fafbc5879",
"md5": "71b299e0f996adbe97c4b9e122b1f87f",
"sha256": "6ceae9eacbe6888c3cff427ed2e2047459f1f132fde24182eadbb6d775450f31"
},
"downloads": -1,
"filename": "elegant_events-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "71b299e0f996adbe97c4b9e122b1f87f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 7502,
"upload_time": "2023-04-20T02:43:43",
"upload_time_iso_8601": "2023-04-20T02:43:43.729503Z",
"url": "https://files.pythonhosted.org/packages/8a/00/a8a8ba5bc5f00be322680760167024721cf63487b07aef70b72fafbc5879/elegant_events-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3f308ad5af2c3c8add3d8970439a75205df0d5ca36db70c282f08752c5f8a00f",
"md5": "f88dabeb19e53d68918b6e5f97dda338",
"sha256": "2057be4cd1fe2b28150f23d78525cf8c368b36077b3a6150c9e7b3a630f78d99"
},
"downloads": -1,
"filename": "elegant_events-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "f88dabeb19e53d68918b6e5f97dda338",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 7347,
"upload_time": "2023-04-20T02:43:45",
"upload_time_iso_8601": "2023-04-20T02:43:45.787325Z",
"url": "https://files.pythonhosted.org/packages/3f/30/8ad5af2c3c8add3d8970439a75205df0d5ca36db70c282f08752c5f8a00f/elegant_events-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-20 02:43:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "jeff-hykin",
"github_project": "elegant_events",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "elegant-events"
}
JSON
