redzed 25.12.30__py3-none-any.whl

redzed/__init__.py

@@ -0,0 +1,44 @@
+"""
+Redzed is a library for building small automated systems.
+
+The redzed package allows to build a so-called "circuit" containing:
+ - logic Blocks with outputs reacting to events
+ - Triggers sending events when certain outputs change
+
+The application code must connect the circuit with outside world.
+
+Copyright (c) 2025 Vlado Potisk <redzed@poti.sk>.
+
+Released under the MIT License.
+
+# Docs: https://redzed.readthedocs.io/en/latest/
+# Home: https://github.com/xitop/redzed/
+"""
+
+__version_info__ = (25, 12, 30)
+__version__ = '.'.join(str(n) for n in __version_info__)
+
+from . import circuit, block, debug, formula_trigger, initializers, undef
+
+from .block import *
+from .circuit import *
+from .debug import *
+from .formula_trigger import *
+from .initializers import *
+from .undef import *
+# .utils not imported
+
+# block library
+from . import blocklib
+from .blocklib import *
+
+__all__ = [
+    '__version__', '__version_info__',
+    *block.__all__,
+    *blocklib.__all__,
+    *circuit.__all__,
+    *debug.__all__,
+    *formula_trigger.__all__,
+    *initializers.__all__,
+    *undef.__all__,
+    ]

redzed/base_block.py

@@ -0,0 +1,132 @@
+"""
+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/
+"""
+from __future__ import annotations
+
+import inspect
+import logging
+import textwrap
+import typing as t
+
+from . import circuit
+from .debug import get_debug_level
+from .undef import UNDEF
+from .utils import check_identifier
+
+_logger = logging.getLogger(__package__)
+
+
+class BlockOrFormula:
+    """
+    The common part of a logic Block or Formula.
+
+    Check the name and register the new item.
+    """
+
+    def __init__(self, name: str, *, comment: str = "") -> None:
+        """Create new circuit component. Add it to the circuit."""
+        # These are the only two allowed concrete subsclasses
+        if not isinstance(self, (block.Block, formula_trigger.Formula)):
+            raise TypeError("Cannot instantiate an abstract class")
+        self.circuit = circuit.get_circuit()
+        check_identifier(name, "Block/Formula name")
+        if name.startswith('_') and not getattr(type(self), 'RZ_RESERVED', False):
+            raise ValueError(f"Name '{name}' is reserved (starting with an underscore)")
+            # reserved blocks cannot be created by simple mistake,
+            # because types of reserved blocks (e.g. Cron) are not public
+        self.name = name
+        self.comment = str(comment)
+        self._str_cached: str|None = None   # cache for __str__ value
+        self.circuit.rz_add_item(self)
+        self._dependent_formulas: set[formula_trigger.Formula] = set()
+        self._dependent_triggers: set[formula_trigger.Trigger] = set()
+        self._output = UNDEF
+
+    @property
+    def type_name(self) -> str:
+        return type(self).__name__
+
+    def has_method(self, method_name: str, async_method: bool = False) -> bool:
+        if not callable(method := getattr(self, method_name, None)):
+            return False
+        if async_method and not inspect.iscoroutinefunction(method):
+            return False
+        return True
+
+    def rz_add_formula(self, formula: formula_trigger.Formula) -> None:
+        """Add a formula block depending on our output value."""
+        self._dependent_formulas.add(formula)
+
+    def rz_add_trigger(self, trigger: formula_trigger.Trigger) -> None:
+        """Add a trigger block depending on our output value."""
+        self._dependent_triggers.add(trigger)
+
+    def _set_output(self, output: t.Any) -> bool:
+        """Set output."""
+        if output is UNDEF:
+            raise ValueError(f"{self}: Cannot set output to <UNDEF>.")
+        if output == self._output:
+            return False
+        if get_debug_level() >= 1:
+            self.log_debug("Output: %r -> %r", self.get(), output)
+        self._output = output
+        return True
+
+    def get(self) -> t.Any:
+        return self._output
+
+    def is_undef(self) -> bool:
+        return self._output is UNDEF
+
+    def log_msg(self, msg: str, *args: t.Any, level: int, **kwargs: t.Any) -> None:
+        """Add own name and log the message with given severity level."""
+        _logger.log(level, f"{self} {msg}", *args, **kwargs)
+
+    def log_debug(self, msg: str, *args: t.Any, **kwargs: t.Any) -> None:
+        """Log a message with DEBUG severity."""
+        self.log_msg(msg, *args, level=logging.DEBUG, **kwargs)
+
+    def log_debug1(self, msg: str, *args: t.Any, **kwargs: t.Any) -> None:
+        """Log a message if debugging is enabled."""
+        if get_debug_level() >= 1:
+            self.log_msg(msg, *args, level=logging.DEBUG, **kwargs)
+
+    def log_debug2(self, msg: str, *args: t.Any, **kwargs: t.Any) -> None:
+        """Log a message if verbose debugging is enabled."""
+        if get_debug_level() >= 2:
+            self.log_msg(msg, *args, level=logging.DEBUG, **kwargs)
+
+    def log_info(self, msg: str, *args: t.Any, **kwargs: t.Any) -> None:
+        """Log a message with _INFO_ severity."""
+        self.log_msg(msg, *args, level=logging.INFO, **kwargs)
+
+    def log_warning(self, msg: str, *args: t.Any, **kwargs: t.Any) -> None:
+        """Log a message with _WARNING_ severity."""
+        self.log_msg(msg, *args, level=logging.WARNING, **kwargs)
+
+    def log_error(self, msg: str, *args: t.Any, **kwargs: t.Any) -> None:
+        """Log a message with _ERROR_ severity."""
+        self.log_msg(msg, *args, level=logging.ERROR, **kwargs)
+
+    def __str__(self) -> str:
+        if self._str_cached is not None:
+            return self._str_cached
+        if not hasattr(self, 'name'):
+            # a subclass did not call super().__init__(name, ...) yet
+            return f"<{self.type_name} N/A id={hex(id(self))}>"
+        parts = [self.type_name, self.name]
+        if self.comment:
+            short_comment = textwrap.shorten(self.comment, width=40, placeholder="...")
+            parts.append(f"comment='{short_comment}'")
+        self._str_cached = f"<{' '.join(parts)}>"
+        return self._str_cached
+
+# Importing at the end resolves a circular import issue.
+# formula_trigger.Formula and block.Block are subclasses of BlockOrFormula defined here.
+# pylint: disable=wrong-import-position
+from . import formula_trigger
+from . import block

redzed/block.py

@@ -0,0 +1,290 @@
+"""
+Logic Blocks.
+- - - - - -
+Part of the redzed package.
+# Docs: https://redzed.readthedocs.io/en/latest/
+# Project home: https://github.com/xitop/redzed/
+"""
+from __future__ import annotations
+
+__all__ = ['Block', 'CircuitShutDown', 'EventData', 'PersistenceFlags', 'UnknownEvent']
+
+import asyncio
+from collections.abc import Callable
+import enum
+import logging
+import typing as t
+
+from .base_block import BlockOrFormula
+from .debug import get_debug_level
+from . import initializers
+from .undef import UNDEF, UndefType
+from .utils import check_identifier, is_multiple, time_period
+
+_logger = logging.getLogger(__package__)
+_DEFAULT_STOP_TIMEOUT = 10.0
+
+
+EventData: t.TypeAlias = dict[str, t.Any]
+
+
+class UnknownEvent(Exception):
+    """Event type not supported."""
+
+
+class CircuitShutDown(RuntimeError):
+    """Cannot perform an action after shutdown."""
+
+
+class PersistenceFlags(enum.IntFlag):
+    """When and how to save block's internal state to the persistent storage."""
+    ENABLED = enum.auto()   # persistent state is enabled
+    # additional options, they may be set only if ENABLED,
+    # EVENT and INTERVAL are mutually exclusive
+    EVENT = enum.auto()     # save after each event
+    INTERVAL = enum.auto()  # save periodically
+
+
+class Block(BlockOrFormula):
+    """
+    A circuit block maintaining its own state.
+
+    Logic blocks accept events and modify their state in response
+    to them. They have one output depending solely on the state.
+    """
+
+    # event handling methods _event_NAME
+    _edt_handlers: dict[str, Callable[[t.Self, EventData], t.Any]]
+    # class attr RZ_PERSISTENCE: is persistent state supported?
+    # instance attr rz_persistence: see PersistenceFlags
+    RZ_PERSISTENCE: bool
+
+    def __init_subclass__(cls, *args, **kwargs) -> None:
+        """
+        Create event dispatch table (edt) of all specialized event handlers.
+
+        Add flag if persistent state is supported.
+        """
+        super().__init_subclass__(*args, **kwargs)
+        cls._edt_handlers = {}
+        for mro in cls.__mro__:
+            if issubclass(mro, Block):
+                for mname, method in vars(mro).items():
+                    if not callable(method):
+                        continue    # it's a plain attr
+                    # When multiple handlers exist, save only the first one, because it has
+                    # the highest rank in the MRO hierarchy.
+                    if len(mname) > 7 and mname.startswith('_event_'):
+                        cls._edt_handlers.setdefault(mname[7:], method)
+
+        cls.RZ_PERSISTENCE = (callable(getattr(cls, 'rz_export_state', None))
+            and callable(getattr(cls, 'rz_restore_state', None)))
+
+    def __init__(
+            self, *args,
+            initial: t.Any = UNDEF,
+            stop_timeout: float|str|UndefType = UNDEF,
+            output_counter: bool = False,
+            output_previous: bool = False,
+            **kwargs
+            ) -> None:
+        """
+        Process arguments.
+
+        Check if given arguments are valid for the particular block type.
+        """
+        if type(self) is Block:     # pylint: disable=unidiomatic-typecheck
+            raise TypeError("Cannot instantiate the base class 'Block'")
+        # remove x_arg=... and X_ARG=... from kwargs before calling super().__init__
+        for key in list(kwargs):
+            if key.startswith(('x_', 'X_')):
+                setattr(self, key, kwargs.pop(key))
+        super().__init__(*args, **kwargs)
+
+        if initial is UNDEF:
+            self.rz_initializers = []
+        else:
+            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):
+                    initial = initializers.InitValue(initial)
+                self.rz_initializers = [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.")
+
+        restore_initializers = [
+            init for init in self.rz_initializers
+            if isinstance(init, initializers.RestoreState)]
+        self.rz_persistence = PersistenceFlags(0)
+        if restore_initializers:
+            if not type(self).RZ_PERSISTENCE:
+                raise TypeError(
+                    f"{self}: 'RestoreState' initializer is not supported by this block type")
+            if len(restore_initializers) != 1:
+                raise ValueError("Multiple 'RestoreState' initializers are not allowed")
+            self.rz_persistence |= PersistenceFlags.ENABLED   # keep the int type
+            init = restore_initializers[0]
+            checkpoints = init.rz_checkpoints
+            if checkpoints == 'event':
+                self.rz_persistence |= PersistenceFlags.EVENT
+            elif checkpoints == 'interval':
+                self.rz_persistence |= PersistenceFlags.INTERVAL
+        self.rz_key = f"{self.type_name}:{self.name}"
+
+        has_astop = self.has_method('rz_astop')
+        self.rz_stop_timeout: float|None
+        if stop_timeout is UNDEF:
+            if has_astop:
+                self.log_debug2("Using default: stop_timeout=%.1f", _DEFAULT_STOP_TIMEOUT)
+                self.rz_stop_timeout = _DEFAULT_STOP_TIMEOUT
+            else:
+                self.rz_stop_timeout = None
+        else:
+            if not has_astop:
+                raise TypeError(
+                    f"{self}: Keyword argument 'stop_timeout' "
+                    + "is not supported by this block type")
+            self.rz_stop_timeout = time_period(stop_timeout)
+        self._etypes_active: set[str] = set()   # events in-progress, disallow event recursion
+        if output_counter and output_previous:
+            raise TypeError(
+                "Options 'output_counter' and 'output_previous' are mutually exclusive.")
+        self._counter = 0 if output_counter else -1
+        self._previous = bool(output_previous)
+        self._init_task: asyncio.Task[t.Any]|None = None
+
+    def rz_set_inittask(self, task: asyncio.Task[t.Any]) -> None:
+        """
+        Give a reference to the task initializing this block.
+
+        We will cancel it when the initialization is done.
+        """
+        self._init_task = task
+
+    def _set_output(self, output: t.Any) -> bool:
+        """
+        Set output, recalculate dependent formulas, run affected triggers.
+        """
+        if self._output is UNDEF and self._init_task is not None:
+            if not self._init_task.done():
+                self._init_task.cancel()
+            self._init_task = None
+        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):
+            return False
+        triggers = self._dependent_triggers.copy()
+        for frm in self._dependent_formulas:
+            triggers |= frm.evaluate()
+        for trg in triggers:
+            trg.run()
+        return True
+
+    def rz_init_default(self) -> None:
+        """
+        Set output to None for blocks that do not have init functions.
+
+        It is assumed that these blocks do not use their output.
+        """
+        if self.is_undef() and not self.has_method('rz_init'):
+            self._set_output(None)
+
+    def _default_event_handler(self, etype: str, edata: EventData) -> t.Any:
+        """Default event handler."""
+        raise UnknownEvent(f"{self}: Unknown event type {etype!r}")
+
+    # note the double underscore: ...vent_ + _get...
+    def _event__get_names(self, _edata: EventData) -> t.Any:
+        """Handle '_get_names' monitoring event."""
+        return {'type': self.type_name, 'name': self.name, 'comment': self.comment}
+
+    def _event__get_output(self, _edata: EventData) -> t.Any:
+        """Handle '_get_state' monitoring event."""
+        return self.get()
+
+    def _event__get_state(self, _edata: EventData) -> t.Any:
+        """Handle '_get_state' monitoring event."""
+        if not self.has_method('rz_export_state'):
+            raise UnknownEvent(f"{self.type_name} blocks do not support this event")
+        if self.is_undef():
+            raise RuntimeError("Not initialized yet")
+        # pylint: disable-next=no-member
+        return self.rz_export_state()         # type: ignore[attr-defined]
+
+    def event(self, etype: str, /, evalue: t.Any = UNDEF, **edata: t.Any) -> t.Any:
+        """
+        An entry point for events.
+
+        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_'):
+            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)
+            elif len(edata) == 1 and 'evalue' in edata:
+                self.log_debug("Got event '%s', evalue: %r", etype, edata['evalue'])
+            else:
+                self.log_debug("Got event '%s', edata: %s", etype, edata)
+        if etype in self._etypes_active:
+            # we must report the error both to the caller and to the runner
+            exc = RuntimeError(
+                f"{self}: Event '{etype}' generated another event of the same type")
+            self.circuit.abort(exc)
+            raise exc
+        self._etypes_active.add(etype)
+        try:
+            if self.is_undef():
+                # We will allow the event, because:
+                #   - some blocks need an event for their initialization
+                #   - this event could have arrived during initialization by chance or race
+                self.log_debug2("Pending event, initializing now")
+                self.circuit.init_block_sync(self)
+            handler = type(self)._edt_handlers.get(etype)
+            try:
+                if handler:
+                    # handler is an unbound method => must add 'self'
+                    retval = handler(self, edata)
+                else:
+                    retval = self._default_event_handler(etype, edata)
+            except UnknownEvent:
+                self.log_debug1("Unknown event error raised")
+                raise
+            except Exception as err:
+                err.add_note(f"Error occurred in {self} during handling of event '{etype}'; "
+                    + f"event data was: {edata if edata else '<EMPTY>'}")
+                if isinstance(err, KeyError) and err.args[0] == 'evalue':
+                    err.add_note("A required event value is almost certainly missing")
+                raise
+            if (self.rz_persistence & PersistenceFlags.EVENT
+                    and not etype.startswith('_get_')       # nothing has changed
+                    and not self.is_undef()):               # nothing to save
+                self.circuit.save_persistent_state(self)
+            self.log_debug2("Event '%s' returned: %r", etype, retval)
+            return retval
+        finally:
+            self._etypes_active.remove(etype)

redzed/blocklib/__init__.py

@@ -0,0 +1,26 @@
+"""
+A library of pre-defined blocks.
+- - - - - -
+Part of the redzed package.
+Docs: https://redzed.readthedocs.io/en/latest/
+Home: https://github.com/xitop/redzed/
+"""
+
+from . import counter, fsm, inputs, outputs, repeat, timedate, timer
+from .counter import *
+from .fsm import *
+from .inputs import *
+from .outputs import *
+from .repeat import *
+from .timedate import *
+from .timer import *
+
+__all__ = [
+    *counter.__all__,
+    *fsm.__all__,
+    *inputs.__all__,
+    *outputs.__all__,
+    *repeat.__all__,
+    *timedate.__all__,
+    *timer.__all__,
+    ]

redzed/blocklib/counter.py

@@ -0,0 +1,45 @@
+"""
+Counter.
+"""
+
+from __future__ import annotations
+
+import redzed
+
+__all__ = ['Counter']
+
+
+class Counter(redzed.Block):
+    """
+    Counter. If modulo is set to a number M, count modulo M.
+    """
+
+    def __init__(self, *args, modulo: int|None = None, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+        if modulo == 0:
+            raise ValueError("modulo must not be zero")
+        self._mod = modulo
+
+    def _setmod(self, value: int) -> int:
+        output = value if self._mod is None else value % self._mod
+        self._set_output(output)
+        return output
+
+    def _event_inc(self, edata: redzed.EventData) -> int:
+        return self._setmod(self._output + edata.get('evalue', 1))
+
+    def _event_dec(self, edata: redzed.EventData) -> int:
+        return self._setmod(self._output - edata.get('evalue', 1))
+
+    def _event_put(self, edata: redzed.EventData) -> int:
+        return self._setmod(edata['evalue'])
+
+    def rz_init_default(self) -> None:
+        self._set_output(0)
+
+    rz_init = _setmod
+
+    def rz_export_state(self):
+        return self.get()
+
+    rz_restore_state = _setmod