event_connect
Devices described by their points, independent of protocol. A protocol package - the one that knows where a value lives and how it is encoded - builds its points and its client on these.
Nothing here performs I/O, sleeps, or knows a protocol, and it depends on nothing but the standard library.
Installation
pip install event-connect
A package built on this one requires a range of versions, such as event_connect>=0.1,<0.2:
every package installed in one Home Assistant shares one copy of it.
What is here
| Module | What it holds |
|---|---|
_key |
Key[T]: a point's key, its text at runtime, carrying the type of its value |
_value |
DataValue[T] and Quality: a value, how far it can be trusted, when and what the device said |
_point |
Point[T], by its behaviour, and its parts: PollRate, Limits, Refresh, Change, Labels, Pulse, WriteKind, Transform |
_scheduler |
Scheduler: which keys are due for a read, and when |
_timing |
Timing: a library's poll intervals, read-back wait and grace before a device counts as not answering, with DEFAULT_TIMING |
_resilience |
The parts a protocol assembles its riding out of a busy, slow or silent device from: Fixed, Exponential, Steps, Jitter; Attempts, Within; Retry; CircuitBreaker |
_passes |
Passes: one pass at a time over what is due; a poll made during one waits for it |
_reachability |
Reachability: whether a device answers, as its consumers should see it, and what to read when it answers again |
_events |
Subscriptions: who is told what, and when a change is a change |
_status |
Status and StatusBoard: what a client knows of its device apart from its points, and who is told when it changes |
_unit |
Unit: units of measurement, with their UCUM codes |
_certainty |
Certainty: how certain it is that a point is what its model says |
_errors |
The errors a client raises |
_clock |
Clock: the monotonic and the wall clock, behind one replaceable object |
_writes |
Write[T]: one write of a sequence |
testing |
FakeClock; FakePoint, a point without a protocol; and Latency, Settling and recommended_refresh, for what a measurement on a device says |
A point
Point[T] holds how a value behaves: how often it is read (poll_rate), what may be written
(limits), its unit, whether it is a setting or a command (write_kind), and what its write
or its change sets off (on_write, on_change). It refuses a contradiction when it is built,
naming every problem at once.
A protocol subclasses it with where the value lives and how it is encoded, says through
readable and writable which sides it has, and adds its own problems to problems().
Reading again
The device sends nothing by itself, and its points are read at different rates, so a change of
one can come long before another that follows from it is read. Refresh(targets, after, until_stable, when=...) names those: read targets after seconds after a write (on_write) or
a change (on_change), and with until_stable, again every after seconds while they still
change, for at most that long - two reads in a row that agree end it, as the same quality and
values no further apart than the point's deadband. when limits a change to one that rises or
falls.
After a write, after left as None waits as long as the written point takes to read back, its
read_back_after; after a change, not at all.
Polling
The scheduler decides; the client reads. due() lists the keys to read now, in order: extra
reads asked for by a refresh, then keys never read, then the most overdue. The client reads them,
then record()s each outcome, which also moves a read-until-settled along. next_due() says when
there is something to do next. Only polled keys - those a consumer subscribed to, or asked to be
polled - are read on their interval or by a refresh; a forced refresh reads any.
One request at a time. A client keeps one request in flight per device, and reads everything
due() lists when the line is free in as few requests as the protocol allows: whatever fell due
while a slow answer was awaited goes out together in the next.
Each key keeps its rhythm. A read a refresh or a retry asked for does not move the next regular one, so keys read together go on being read together, in one request, whatever is read in between. Nothing is read early to join another request: a refresh waits for a reason.
A failed read is tried again when the protocol says so. Only the protocol knows what a
failure means - a busy device, a gateway that has nothing yet, a device gone silent behind its own
backoff - so it says, when it records a read, how soon it wants it read again; without that, the
read waits for its rhythm. A device that answers again after silence is best read in full at once,
which reset() does.
One lost answer is not an outage. Reachability says a device answers as soon as it does,
and that it does not only once it has been silent for offline_after seconds, counted from the
first unanswered request. Meanwhile its values are stale - the last good ones. Given the
scheduler, answered(scheduler) makes due at once what failed while the device was silent, and
everything once it had counted as not answering; that it stopped answering and answers again is
logged once each.
Building a protocol package on it
- Points: subclass
Pointwith where a value lives and how it is encoded; say throughreadableandwritablewhich sides it has; add the protocol's own checks toproblems(). - Timing: give the package one
Timing, measured on its devices: the poll intervals, how long a write takes to show, how long a device may be silent. A client takes another where a device needs it. How long one request may take and any gap a connection needs between requests belong to the connection, not to the timing. - Riding out failures: assemble it from the parts in
_resilience, so that every protocol says it the same way and a model can choose its own: aRetryof aWaitand aStopfor what is tried again at once, such as a busy answer; aCircuitBreakerfor a device gone silent, so that it is not asked again and again; and aretry_aftergiven torecord()for a read the device should be asked for again soon. Let a model set them in its options, and whoever creates the device override the model. - Client: keep one request in flight per device, and run each pass through
Passes, so that polls made together cause one pass. Read whatdue()lists in as few requests as the protocol allows,record()every key read with whether it was answered, tell aReachabilityof every request, answered or not, keep the statuses in aStatusBoard, and sleep untilnext_due()- or for a short tick, whichever comes first - between passes. - Refreshes: name in
on_changewhat a change affects and inon_writewhat a write disturbs, with the waits anduntil_stablemeasured on a device, and adeadbandon a value that jitters, so that it can be seen to settle. - Measuring: time a device's answers into a
Latency, and the readings after a change into aSettling;recommended_refreshturns the slowest settling into anafterand anuntil_stable.
Riding out failures
Each part decides, and does nothing: a protocol asks it and acts.
from event_connect import Attempts, CircuitBreaker, Exponential, Fixed, Jitter, Retry, Steps, Within
busy = Retry(wait=Exponential(0.2, factor=2), stop=Attempts(4)) # a busy answer
zeros = Retry(wait=Steps(0.5, then=Fixed(1)), stop=Within(7.5)) # a gateway with nothing yet
silent = CircuitBreaker(after=3, pause=Jitter(Exponential(10, factor=2, max=120))) # a device gone silent
delay = busy.next_delay(attempts=1, elapsed=0.0) # 0.2; None once it is time to give up
breaker = silent.breaker() # one per device
attempt = breaker.attempt(now) # None while it is open
if attempt is not None:
with attempt: # a probe never told its outcome is released
... # send; then attempt.answered() or attempt.unanswered(now)
| Part | Decides |
|---|---|
Fixed(s), Exponential(start, factor, max), Steps(a, b, ..., then=), Jitter(wait, spread) |
how long to wait before the next try |
Attempts(n), Within(s), and a | b |
when to give up |
Retry(wait, stop) |
the wait before each try again, until it gives up |
CircuitBreaker(after, pause) |
when to stop asking a silent device, for how long, and to let one probe through after |
License
MIT
Metadata
Release files for event-connect 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| event_connect-0.3.0.tar.gz | 53.2 kB | With provenance | Details for event_connect-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| event_connect-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for event_connect-0.3.0-py3-none-any.whl |
Total release size: 85.9 kB
Release files / event_connect-0.3.0.tar.gz
| Download URL | event_connect-0.3.0.tar.gz |
|---|---|
| Size | 53.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d48c650044ac1d35dbbb9dfbd54c4531a20260355dbfbf318d60fb0238c58db4
|
|
BLAKE2b-256 checksum How to use checksums |
3201cd897a7c0418349e5a09e2d03d4679b2000314abfb114dcb52f1db931304
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.
Transparency logRelease files / event_connect-0.3.0-py3-none-any.whl
| Download URL | event_connect-0.3.0-py3-none-any.whl |
|---|---|
| Size | 32.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
327b8312457634ef9c67c4914a5c63119c805fb6b9a42b4a841f4fd7a3c36b7a
|
|
BLAKE2b-256 checksum How to use checksums |
a183809794c612d90817102abe31d66552b909bba5b5d5aab818e4de81ae7fe8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.
Transparency logSecurity for event-connect 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for event_connect-0.3.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.