redzed 25.12.30__py3-none-any.whl → 26.2.4__py3-none-any.whl

redzed/__init__.py

@@ -7,15 +7,15 @@ The redzed package allows to build a so-called "circuit" containing:
 
 The application code must connect the circuit with outside world.
 
-Copyright (c) 2025 Vlado Potisk <redzed@poti.sk>.
+Copyright (c) 2025-2026 Vlado Potisk <redzed@poti.sk>.
 
 Released under the MIT License.
 
-# Docs: https://redzed.readthedocs.io/en/latest/
-# Home: https://github.com/xitop/redzed/
+Docs: https://redzed.readthedocs.io/en/latest/
+Home: https://github.com/xitop/redzed/
 """
 
-__version_info__ = (25, 12, 30)
+__version_info__ = (26, 2, 4)
 __version__ = '.'.join(str(n) for n in __version_info__)
 
 from . import circuit, block, debug, formula_trigger, initializers, undef

redzed/base_block.py

@@ -2,8 +2,8 @@
 Base class of logic Blocks and Formulas.
 - - - - - -
 Part of the redzed package.
-# Docs: https://redzed.readthedocs.io/en/latest/
-# Project home: https://github.com/xitop/redzed/
+Docs: https://redzed.readthedocs.io/en/latest/
+Project home: https://github.com/xitop/redzed/
 """
 from __future__ import annotations
 

redzed/block.py

@@ -2,8 +2,8 @@
 Logic Blocks.
 - - - - - -
 Part of the redzed package.
-# Docs: https://redzed.readthedocs.io/en/latest/
-# Project home: https://github.com/xitop/redzed/
+Docs: https://redzed.readthedocs.io/en/latest/
+Project home: https://github.com/xitop/redzed/
 """
 from __future__ import annotations
 
@@ -45,6 +45,9 @@ class PersistenceFlags(enum.IntFlag):
     INTERVAL = enum.auto()  # save periodically
 
 
+_INIT_TYPES = (initializers.SyncInitializer, initializers.AsyncInitializer)
+
+
 class Block(BlockOrFormula):
     """
     A circuit block maintaining its own state.
@@ -107,23 +110,18 @@ class Block(BlockOrFormula):
             if not self.has_method('rz_init'):
                 raise TypeError(
                     f"{self}: Keyword argument 'initial' is not supported by this block type")
-            init_types = (initializers.SyncInitializer, initializers.AsyncInitializer)
             if not is_multiple(initial):
-                if not isinstance(initial, init_types):
+                if not isinstance(initial, _INIT_TYPES):
                     initial = initializers.InitValue(initial)
                 self.rz_initializers = [initial]
+            elif any(isinstance(init, _INIT_TYPES) for init in initial):
+                # sequence of initializers
+                self.rz_initializers = [
+                    init if isinstance(init, _INIT_TYPES) else initializers.InitValue(init)
+                    for init in initial]
             else:
-                init_cnt = sum(1 for init in initial if isinstance(init, init_types))
-                if init_cnt == 0:
-                    # single value which happens to be a sequence
-                    self.rz_initializers = [initializers.InitValue(initial)]
-                elif init_cnt == len(initial):
-                    # sequence of initializers
-                    self.rz_initializers = initial
-                else:
-                    raise TypeError(
-                        f"{self}: Check the initial argument. "
-                        + "A non-initializer was found in the sequence of initializers.")
+                # single value which happens to be a sequence
+                self.rz_initializers = [initializers.InitValue(initial)]
 
         restore_initializers = [
             init for init in self.rz_initializers
@@ -185,8 +183,6 @@ class Block(BlockOrFormula):
         if self._counter >= 0:
             output = (output, self._counter)
             self._counter += 1
-            if self._counter >= 2**48:    # more than enough for this purpose
-                self._counter = 0
         if self._previous:
             output = (output, self._output)
         if not super()._set_output(output):
@@ -229,6 +225,9 @@ class Block(BlockOrFormula):
         # pylint: disable-next=no-member
         return self.rz_export_state()         # type: ignore[attr-defined]
 
+    def rz_is_shut_down(self) -> bool:
+        return self.circuit.is_shut_down()
+
     def event(self, etype: str, /, evalue: t.Any = UNDEF, **edata: t.Any) -> t.Any:
         """
         An entry point for events.
@@ -236,13 +235,13 @@ class Block(BlockOrFormula):
         Call the specialized _event_ETYPE() method if it exists.
         Otherwise call the _default_event_handler() as the last resort.
         """
-        if self.circuit.after_shutdown() and not etype.startswith('_get_'):
+        check_identifier(etype, "Event type")
+        if not etype.startswith('_get_') and self.rz_is_shut_down():
             raise CircuitShutDown("The circuit was shut down")
 
         if evalue is not UNDEF:
             edata['evalue'] = evalue
 
-        check_identifier(etype, "Event type")
         if get_debug_level() >= 1:
             if not edata:
                 self.log_debug("Got event '%s'", etype)

redzed/blocklib/counter.py

@@ -1,5 +1,9 @@
 """
 Counter.
+- - - - - -
+Part of the redzed package.
+Docs: https://redzed.readthedocs.io/en/latest/
+Home: https://github.com/xitop/redzed/
 """
 
 from __future__ import annotations

redzed/blocklib/fsm.py

@@ -1,7 +1,7 @@
 """
 Event driven finite-state machine (FSM) extended with optional timers.
-
 - - - - - -
+Part of the redzed package.
 Docs: https://redzed.readthedocs.io/en/latest/
 Home: https://github.com/xitop/redzed/
 """
@@ -43,7 +43,7 @@ def _hook_args(func: Callable[..., t.Any]) -> int:
     """Check if *func* takes 0 or 1 argument."""
     params = inspect.signature(func).parameters
     plen = len(params)
-    if plen > 1 or any(p.kind not in _ALLOWED_KINDS for p in params.values()):
+    if plen > 1 or plen == 1 and next(iter(params.values())).kind not in _ALLOWED_KINDS:
         raise TypeError(
             f"Function {func.__name__} is not usable as an FSM hook "
             + "(incompatible call signature)")
@@ -56,15 +56,15 @@ class FSM(redzed.Block):
     """
 
     # subclasses should define:
-    ALL_STATES: Sequence[str] = []
-    TIMED_STATES: Sequence[Sequence] = []
-        # each timed state: [state, duration, next_state]
+    STATES: Sequence[str|Sequence] = []
+        # each state: non-timed: state
+        #             or timed: [state, duration, next_state]
     EVENTS: Sequence[Sequence] = []
         # each item: [event, [state1, state2, ..., stateN], next_state]
         #        or: [event, ..., next_state] <- literal ellipsis
     # --- and redzed will translate that to: ---
     _ct_default_state: str
-        # the default initial state (first item of ALL_STATES)
+        # the default initial state (first item of STATES)
     _ct_duration: dict[str, float]
         # {timed_state: default_duration_in_seconds}
     _ct_events: set[str]
@@ -85,7 +85,7 @@ class FSM(redzed.Block):
     @classmethod
     def _check_state(cls, state: str) -> None:
         if state not in cls._ct_states:
-            raise ValueError(f"FSM state '{state}' is unknown (missing in ALL_STATES)")
+            raise ValueError(f"FSM state '{state}' is unknown (missing in STATES)")
 
     @classmethod
     def _add_transition(cls, event: str, state: str|None, next_state: str|None) -> None:
@@ -100,64 +100,93 @@ class FSM(redzed.Block):
     @classmethod
     def _build_tables(cls) -> None:
         """
-        Build control tables from ALL_STATES, TIMED_STATES and EVENTS.
+        Build control tables from STATES and EVENTS.
 
         Control tables must be created for each subclass. The original
         tables are left unchanged. All control tables are class
         variables and have the '_ct_' prefix.
         """
         # states
-        if not is_multiple(cls.ALL_STATES) or not cls.ALL_STATES:
-            raise ValueError("ALL_STATES: Expecting non-empty sequence of names")
-        for state in cls.ALL_STATES:
-            check_identifier(state, "FSM state name")
-        cls._ct_states = set(cls.ALL_STATES)
-        cls._ct_default_state = cls.ALL_STATES[0]
+        if not is_multiple(cls.STATES) or not cls.STATES:
+            raise ValueError("STATES: Expecting a non-empty sequence of states")
+        cls._ct_states = set()
+        timed_states: list[tuple[int, Sequence]] = []
+        for i, entry in enumerate(cls.STATES, start=1):
+            try:
+                if is_multiple(entry):
+                    if len(entry) != 3:
+                        raise ValueError(
+                            "Invalid timed state definition. "
+                            + "Expected are three values: state, duration, next_state")
+                    timed_states.append((i, entry))
+                    state = entry[0]
+                else:
+                    state = entry
+                check_identifier(state, "FSM state name")
+                if i == 1:
+                    cls._ct_default_state = state
+                elif state in cls._ct_states:
+                    raise ValueError(f"Duplicate definition for state '{state}'")
+                cls._ct_states.add(state)
+            except (ValueError, TypeError) as err:
+                err.add_note(f"Offending entry: STATES table, item {i}")
+                raise
+
         # timed states
         cls._ct_duration = {}
         cls._ct_timed_states = {}
-        for state, duration, next_state in cls.TIMED_STATES:
-            cls._check_state(state)
-            cls._check_state(next_state)
-            if state in cls._ct_timed_states:
-                raise ValueError(f"TIMED_STATES: Multiple rules for timed state '{state}'")
-            if duration is not None:
-                try:
-                    cls._ct_duration[state] = time_period(duration, zero_ok=True)
-                except (ValueError, TypeError) as err:
-                    raise ValueError(
-                        f"TIMED_STATES: could not convert duration of state '{state}' "
-                        + f"to seconds: {err}") from None
-            cls._ct_timed_states[state] = next_state
+        for i, (state, duration, next_state) in timed_states:
+            try:
+                # state was checked already, also for duplicates
+                cls._check_state(next_state)
+                if duration is not None:
+                    try:
+                        cls._ct_duration[state] = time_period(duration, zero_ok=True)
+                    except (ValueError, TypeError) as err:
+                        raise ValueError(
+                            f"Could not convert duration of state '{state}' to seconds: {err}"
+                            ) from None
+                cls._ct_timed_states[state] = next_state
+            except (ValueError, TypeError) as err:
+                err.add_note(f"Offending entry: STATES table, item {i}")
+                raise
+
 
         # events and state transitions
         cls._ct_transition = {}
         cls._ct_events = set()
-        for event, from_states, next_state in cls.EVENTS:
-            check_identifier(event, "FSM event name")
-            if event in cls._edt_handlers:
-                raise ValueError(
-                    f"Ambiguous event '{event}': "
-                    + "the name is used for both FSM and Block event")
-            cls._ct_events.add(event)
-            if next_state is not None:
-                cls._check_state(next_state)
-            if from_states is ...:
-                # The ellipsis means any state. In control tables we are using None instead
-                cls._add_transition(event, None, next_state)
-            else:
-                if not is_multiple(from_states):
-                    exc = ValueError(
-                        "Expected is a literal ellipsis (...) or a sequence of states, "
-                        + f"got {from_states!r}")
-                    exc.add_note(
-                        f"Problem was found in the transition rule for event '{event}'")
-                    if from_states in cls._ct_states:
-                        exc.add_note(f"Did you mean: ['{from_states}'] ?")
-                    raise exc
-                for fstate in from_states:
-                    cls._check_state(fstate)
-                    cls._add_transition(event, fstate, next_state)
+        for i, (event, from_states, next_state) in enumerate(cls.EVENTS, start=1):
+            try:
+                j = 1
+                check_identifier(event, "FSM event name")
+                if event in cls._edt_handlers:
+                    raise ValueError(
+                        f"Ambiguous event '{event}': "
+                        + "the name is used for both FSM and Block event")
+                cls._ct_events.add(event)
+                j = 2
+                if from_states is ...:
+                    # The ellipsis means any state. In control tables we are using None instead
+                    cls._add_transition(event, None, next_state)
+                else:
+                    if not is_multiple(from_states):
+                        if from_states in cls._ct_states:
+                            hint = f" Did you mean: ['{from_states}'] ?"
+                        else:
+                            hint = ""
+                        raise ValueError(
+                            "Expected is a literal ellipsis (...) or a sequence of states, "
+                            + f"got {from_states!r}{hint}")
+                    for fstate in from_states:
+                        cls._check_state(fstate)
+                        cls._add_transition(event, fstate, next_state)
+                j = 3
+                if next_state is not None:
+                    cls._check_state(next_state)
+            except (ValueError, TypeError) as err:
+                # pylint: disable-next=used-before-assignment
+                err.add_note(f"Offending entry: EVENTS table, item {i}, position: {j}/3")
+                raise
 
         # helper table: name 'prefix_suffix' is valid if prefix is a dict key
         # and suffix is listed in the corresponding dict value

redzed/blocklib/inputs.py

@@ -2,8 +2,8 @@
 A single memory cell blocks for general use.
 - - - - - -
 Part of the redzed package.
-Docs: https://edzed.readthedocs.io/en/latest/
-Home: https://github.com/xitop/edzed/
+Docs: https://redzed.readthedocs.io/en/latest/
+Home: https://github.com/xitop/redzed/
 """
 from __future__ import annotations
 
@@ -17,39 +17,7 @@ import typing as t
 import redzed
 from redzed.utils import is_multiple, time_period
 from .fsm import FSM
-
-
-class _Validate(redzed.Block):
-    """
-    Add a value validator.
-    """
-
-    def __init__(
-            self, *args,
-            validator: Callable[[t.Any], t.Any]|None = None,
-            **kwargs) -> None:
-        self._validator = validator
-        super().__init__(*args, **kwargs)
-
-    def _validate(self, value: t.Any) -> t.Any:
-        """
-        Return the value processed by the validator.
-
-        Return UNDEF if the validator rejected the value by raising
-        an exception. Return the value unchanged if a validator was
-        not configured.
-        """
-        if self._validator is None or value is redzed.UNDEF:
-            return value
-        try:
-            validated = self._validator(value)
-        except Exception as err:
-            self.log_debug1(
-                "Validator rejected value %r with %s: %s", value, type(err).__name__, err)
-            return redzed.UNDEF
-        if validated != value:
-            self.log_debug2("Validator has rewritten %r -> %r", value, validated)
-        return validated
+from .validator import _Validate
 
 
 class Memory(_Validate, redzed.Block):
@@ -59,29 +27,28 @@ class Memory(_Validate, redzed.Block):
     Memory is typically used as an input block.
     """
 
-    def _store_value(self, value: t.Any) -> bool:
-        """
-        Validate and store a value.
-
-        Return True on success, False on validation error.
-        """
-        if (validated := self._validate(value)) is redzed.UNDEF:
-            return False
-        self._set_output(validated)
-        return True
-
     def _event_store(self, edata: redzed.EventData) -> bool:
+        """Validate and store a value."""
         evalue = edata['evalue']
-        return self._store_value(evalue)
+        try:
+            validated = self._validate(evalue)
+        except Exception:
+            if edata.get('suppress', False):
+                return False
+            raise
+        self._set_output(validated)
+        return True
 
     def rz_init(self, init_value: t.Any, /) -> None:
-        self._store_value(init_value)
+        validated = self._validate(init_value)
+        self._set_output(validated)
 
     def rz_export_state(self) -> t.Any:
         return self.get()
 
     def rz_restore_state(self, state: t.Any, /) -> None:
-        self._store_value(state)
+        # Do not validate. *state* is already validated and thus possibly preprocessed.
+        self._set_output(state)
 
 
 class MemoryExp(_Validate, FSM):
@@ -89,8 +56,7 @@ class MemoryExp(_Validate, FSM):
     Memory cell with an expiration time.
     """
 
-    ALL_STATES = ['expired', 'valid']
-    TIMED_STATES = [ ['valid', None, 'expired'], ]
+    STATES = ['expired', ['valid', None, 'expired']]
 
     def __init__(
             self, *args,
@@ -98,25 +64,33 @@ class MemoryExp(_Validate, FSM):
             expired: t.Any = None,
             **kwargs) -> None:  # kwargs may contain a validator
         super().__init__(*args, t_valid=duration, **kwargs)
-        self._expired = self._validate(expired)
-        if self._expired is redzed.UNDEF:
-            raise ValueError(
-                f"{self} The 'expired' argument {expired!r} was rejected by the validator")
+        try:
+            self._expired = self._validate(expired)
+        except Exception as err:
+            err.add_note(f"{self}: The validator rejected the 'expired' argument {expired!r}")
+            raise
 
-    def _event_store(self, edata: redzed.EventData) -> bool:
-        evalue = edata['evalue']
-        if (validated := self._validate(evalue)) is redzed.UNDEF:
-            return False
+    def _store(self, validated: t.Any) -> None:
         if validated == self._expired:
             self._goto('expired')
         else:
             self.sdata['memory'] = validated
             self._goto('valid')
+
+    def _event_store(self, edata: redzed.EventData) -> bool:
+        evalue = edata['evalue']
+        validated = self._validate(evalue)
+        try:
+            validated = self._validate(evalue)
+        except Exception:
+            if edata.get('suppress', False):
+                return False
+            raise
+        self._store(validated)
         return True
 
     def rz_init(self, init_value: t.Any, /) -> None:
-        if (validated := self._validate(init_value)) is redzed.UNDEF:
-            return
+        validated = self._validate(init_value)
         if validated == self._expired:
             super().rz_init('expired')
         else:
@@ -131,7 +105,7 @@ class MemoryExp(_Validate, FSM):
             self.sdata['memory'] if self.state == 'valid' else self._expired)
 
 
-class DataPoll(_Validate, redzed.Block):
+class DataPoll(redzed.Block):
     """
     A source of sampled or computed values.
     """
@@ -180,7 +154,7 @@ class DataPoll(_Validate, redzed.Block):
                 duration = time.monotonic() - start_ts
             else:
                 duration = 0
-            if (value := self._validate(value)) is redzed.UNDEF:
+            if value is redzed.UNDEF:
                 failures += 1
                 self.log_debug1("Data acquisition failure(s): %d", failures)
                 if 0 < self._abort_after_failures <= failures:
@@ -205,6 +179,4 @@ class DataPoll(_Validate, redzed.Block):
     def rz_export_state(self) -> t.Any:
         return self.get()
 
-    def rz_restore_state(self, state: t.Any, /) -> None:
-        if (value := self._validate(state)) is not redzed.UNDEF:
-            self._set_output(value)
+    rz_restore_state = rz_init