|
| 1 | +"""Idempotently bring a control or setting to a desired state: read, act, verify. |
| 2 | +
|
| 3 | +Automation that *acts unconditionally* — "click the checkbox", "type the value" |
| 4 | +— double-toggles a box that was already checked, or re-enters a field that was |
| 5 | +already correct, and can't be safely re-run. The robust shape is |
| 6 | +read-compare-act-verify: look at the current state, do nothing if it already |
| 7 | +matches, otherwise apply the change and confirm it took. ``ensure_state`` is |
| 8 | +that primitive. |
| 9 | +
|
| 10 | +* :func:`ensure_state` — generic: read via ``reader``, and if it doesn't equal |
| 11 | + ``desired`` apply ``setter`` and re-read, up to ``attempts`` times. |
| 12 | +* :func:`ensure_toggle` — the boolean specialization for a stateless flip: read |
| 13 | + ``is_on`` and call ``toggle`` only while it differs from ``desired``. |
| 14 | +
|
| 15 | +A control already in the desired state is left untouched (``changed=False``), |
| 16 | +so the call is idempotent and safe to re-run. The reader / setter / toggle seams |
| 17 | +are injectable, so the logic is fully testable without a real control. Distinct |
| 18 | +from :mod:`idempotency` (a request-key replay cache) — this converges *device |
| 19 | +state*, not call results. Imports no ``PySide6``. |
| 20 | +""" |
| 21 | +from typing import Any, Callable, Dict |
| 22 | + |
| 23 | +StateReader = Callable[[], Any] |
| 24 | +StateSetter = Callable[[Any], None] |
| 25 | +StateEquals = Callable[[Any, Any], bool] |
| 26 | + |
| 27 | + |
| 28 | +def _default_equals(left: Any, right: Any) -> bool: |
| 29 | + """Default equality used to decide whether the state already matches.""" |
| 30 | + return left == right |
| 31 | + |
| 32 | + |
| 33 | +def ensure_state(desired: Any, *, reader: StateReader, setter: StateSetter, |
| 34 | + equals: StateEquals = _default_equals, |
| 35 | + attempts: int = 2) -> Dict[str, Any]: |
| 36 | + """Bring the state read by ``reader`` to ``desired`` via ``setter`` (idempotent). |
| 37 | +
|
| 38 | + Reads the current state; if ``equals(current, desired)`` it returns |
| 39 | + immediately with ``changed=False``. Otherwise it applies ``setter(desired)`` |
| 40 | + and re-reads, up to ``attempts`` times. Returns |
| 41 | + ``{ok, changed, value, attempts}``. |
| 42 | + """ |
| 43 | + current = reader() |
| 44 | + if equals(current, desired): |
| 45 | + return {"ok": True, "changed": False, "value": current, "attempts": 0} |
| 46 | + used = 0 |
| 47 | + for used in range(1, max(1, int(attempts)) + 1): |
| 48 | + setter(desired) |
| 49 | + current = reader() |
| 50 | + if equals(current, desired): |
| 51 | + return {"ok": True, "changed": True, "value": current, |
| 52 | + "attempts": used} |
| 53 | + return {"ok": False, "changed": True, "value": current, "attempts": used} |
| 54 | + |
| 55 | + |
| 56 | +def ensure_toggle(desired: bool, *, is_on: Callable[[], bool], |
| 57 | + toggle: Callable[[], None], |
| 58 | + attempts: int = 2) -> Dict[str, Any]: |
| 59 | + """Bring a boolean toggle to ``desired`` by flipping only while it differs. |
| 60 | +
|
| 61 | + ``is_on`` reads the current boolean; ``toggle`` performs a stateless flip and |
| 62 | + is called only when the state does not already match ``desired``. Returns |
| 63 | + ``{ok, changed, value, attempts}``. |
| 64 | + """ |
| 65 | + return ensure_state(bool(desired), reader=lambda: bool(is_on()), |
| 66 | + setter=lambda _desired: toggle(), attempts=attempts) |
0 commit comments