Skip to main content

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 an exporter.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 with exporter.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 the publisher_id of the signal's publisher, and pass in the event 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: Initialization and Subscribing

Publishing, Awaiting, and Responding: 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 for pytest and pytest-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


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

state-signals-1.0.1.tar.gz (22.8 kB view details)

Uploaded Source

Built Distribution

state_signals-1.0.1-py3-none-any.whl (21.5 kB view details)

Uploaded Python 3

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

Hashes for state-signals-1.0.1.tar.gz
Algorithm Hash digest
SHA256 20e441ed293d4e7d3c99bb612cdb1317add313b33f57d9a1b9b2fbf83c6d8b76
MD5 b68e75803be62b949efabaee0177f29c
BLAKE2b-256 6cef97079ea9ebb72c18373204981dbe0f75155c745864dd2242da672e545f15

See more details on using hashes here.

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

Hashes for state_signals-1.0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 289c93e81af651a11738a0808c305008a526a18211544579015ee4deb3327c12
MD5 baeb990b39b8dbb1cbad2641609c2cc8
BLAKE2b-256 5f63c9823cbda9a809acdb0e3f51d6c3bdd2873e56be08627e062ef83a1b4daf

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page