Package for easy management of state/event signal publishing, subscribing, and responding
Project description
state-signals: the State/Event Signal Module
A python package for handling state/event signals
Adds two new, simple-to-use objects:
- SignalExporter (for publishing state signals and handling subscribers + responses)
- SignalResponder (for receiving state signals, locking onto publishers, and publishing responses)
Also provides two dataclass specifications:
- Signal (state signal protocol payload definition)
- Response (response protocol payload definition)
Combining redis pubsub features with state signal + response protocols, these additions make state signal publishing, subscribing, receiving, and responding incredibly easy to integrate into any python code.
See full documentation here
Installation
The state-signals PyPI package is available here
- To install, run
pip install state-signals
There are also state-signals RPMs available:
- For python 3.6, use
python36-state_signals
- For python 3.7 or later, use
python3-state_signals
- Both can be found here
Requirements
The use of this module requires the existence of an accessible redis server.
- Redis can easily be installed with a
yum install redis
(or replace yum with package manager of choice). - A redis container can also be started using the official image
A redis server can be started with the redis-server
command.
- The default port is 6379 (also default for state-signals), but can be changed with
--port (port)
- A config file can also be used for greater control/detail
redis-server \path\to\config
- Example config available here
See https://redis.io/ for more details and usage
Note that state-signals also works with any redis-compatible pub/sub databases (like KeyDB)
Protocol / Behaviors
The Signal
and Response
dataclasses define the exact fields/format of signal and response payloads.
Publishing, receiving, and responding mechanisms are all detailed in SignalExporter
and SignalResponder
documentation. Below are details on the subscribing/awaiting protocol.
Accept Subscribers and Awaiting Responses:
- Using the
SignalExporter
, call anexporter.initialize(legal_events, ...)
- Initialization will start the subscriber listener and establish legal event names
- It will also publish an "initialization" state signal
- Responders can then respond to the "initialization" signal to be added to the list of subs
- Note: A responder can subscribe at any point, unless a "shutdown" signal has been published after the initialization
- The
SignalExporter
will now wait for (up until timeout) and read the responses of the subscribers after publishing any further signals withexporter.publish_signal(event, ...)
- When finished, calling
exporter.shutdown(...)
will stop the subscriber listener, wipe the subscriber list, and publish a "shutdown" signal- This signal publish will NOT listen for responses
Sending Responses
- Receiving signals and sending responses can be done with the
SignalResponder
- To respond to a signal, simply use the
respond
method and pass in thepublisher_id
of the signal's publisher, and pass in theevent
being responded to. - (NEW IN v0.2.0)
srespond(signal, ...)
: A method where the user can simply pass in the received signal object they wish to respond to instead of the signal's id/event - Responding to an "initialization" signal will subscribe the responder to that specific publisher, which will now await responses from the responder for any future signals published.
- NOTE: When responding to an "initialization" signal, a Response-Action-Success (RAS) code is not necessary
- For any future responses to that publisher's signals, an RAS code will be necessary, and will indicate to the publisher whether or not the responder was successful in acting upon the signal
- See documentation for more details on RAS codes
Initialization and Subscribing:
Publishing, Awaiting, and Responding:
See the full documentation for further details, options, and more
Development
Formatting
- For formatting, get black v22.3.0 via
pip install black==22.3.0
- To check any modified python files, run
black --check (file)
- To check the entire repo, run
black --check .
from the top-level - To auto-format all python code, remove the
--check
option
Testing
- Testing is done with pytest
- Run a
pip install
forpytest
andpytest-mock
- To run the tests, run
pytest -v
from the top-level - Any new test functions/scripts can be added into the
tests
folder - NOTE: You will need to run a local
redis-server
for the functional tests to pass
Both formatting checks and tests must pass for GH Actions to approve a commit
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file state-signals-1.0.1.tar.gz
.
File metadata
- Download URL: state-signals-1.0.1.tar.gz
- Upload date:
- Size: 22.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.1.7 CPython/3.6.8 Linux/4.18.0-372.19.1.el8_6.x86_64
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 20e441ed293d4e7d3c99bb612cdb1317add313b33f57d9a1b9b2fbf83c6d8b76 |
|
MD5 | b68e75803be62b949efabaee0177f29c |
|
BLAKE2b-256 | 6cef97079ea9ebb72c18373204981dbe0f75155c745864dd2242da672e545f15 |
File details
Details for the file state_signals-1.0.1-py3-none-any.whl
.
File metadata
- Download URL: state_signals-1.0.1-py3-none-any.whl
- Upload date:
- Size: 21.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.1.7 CPython/3.6.8 Linux/4.18.0-372.19.1.el8_6.x86_64
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 289c93e81af651a11738a0808c305008a526a18211544579015ee4deb3327c12 |
|
MD5 | baeb990b39b8dbb1cbad2641609c2cc8 |
|
BLAKE2b-256 | 5f63c9823cbda9a809acdb0e3f51d6c3bdd2873e56be08627e062ef83a1b4daf |