redzed 25.12.30__py3-none-any.whl

redzed/cron_service.py

@@ -0,0 +1,243 @@
+"""
+Call the .rz_cron_event() method of all registered blocks at given times of day.
+
+Blocks acting on given time, date and weekdays are implemented
+on top of this low-level service.
+
+- - - - - -
+Docs: https://redzed.readthedocs.io/en/latest/
+Home: https://github.com/xitop/redzed/
+"""
+from __future__ import annotations
+
+import asyncio
+import bisect
+from collections.abc import Collection
+import datetime as dt
+import time
+import typing as t
+
+from .block import Block, EventData
+from .debug import get_debug_level
+from .utils import SEC_PER_HOUR, SEC_PER_MIN, SEC_PER_DAY
+
+# time tracking accuracy (in seconds)
+_TT_OK = 0.001          # desired accuracy
+_TT_WARNING = 0.1       # log a warning when exceeded
+_TT_ERROR = 2.5         # do a reset when exceeded
+_SYNC_SLEEP = 0.000_2   # sleeps <= 200 µs can be blocking for sake of accuracy
+
+# hourly wake-ups for precise time tracking and early detection of DST changes
+_SET24 = frozenset(dt.time(hour, 0, 0) for hour in range(24))
+
+
+class Cron(Block):
+    """
+    Simple cron service.
+
+    Do not use directly in circuits. It has a form of a logic block
+    only to allow monitoring through the event interface.
+    """
+
+    RZ_RESERVED = True
+
+    def __init__(self, *args, utc: bool, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+        self._utc = bool(utc)
+        self._alarms: dict[dt.time, set[Block]] = {}
+        self._reversed: dict[Block, set[dt.time]] = {}
+        self._do_reload = asyncio.Event()
+
+    def rz_start(self) -> None:
+        tz = 'UTC' if self._utc else 'local time'
+        self.circuit.create_service(self._cron_daemon(), name=f"cron daemon ({tz})")
+
+    def dtnow(self) -> dt.datetime:
+        """Return the current date/time."""
+        if self._utc:
+            # but we need to keep all date/time object timezone naive
+            # in order to make them mutually comparable
+            return dt.datetime.now(dt.UTC).replace(tzinfo=None)
+        return dt.datetime.now()
+
+    def _check_tz(self, time_of_day: dt.time) -> None:
+        """Check if the time zone is left unspecified (i.e. object is "naive")."""
+        if not isinstance(time_of_day, dt.time):
+            raise TypeError(
+                f"time_of_day should be a datetime.time object, but got {time_of_day!r}")
+        if time_of_day.tzinfo is not None:
+            raise ValueError("time_of_day must not contain timezone data")
+
+    def set_schedule(self, blk: Block, times_of_day: Collection[dt.time]) -> None:
+        """
+        Add a block to be activated at given times or update its schedule.
+
+        The block's 'rz_cron_event' method will be called at given time
+        and also when this service is started, reset or reloaded.
+
+        A datetime.datetime object will be passed to the blk as its
+        only argument.
+        """
+        if not hasattr(blk, 'rz_cron_event'):
+            raise TypeError(f"{blk} is not compatible with the cron service")
+
+        times_of_day = set(times_of_day) # make a set, make a copy
+        # remove old times of day
+        old_times = self._reversed.get(blk, set())
+        for tod in old_times - times_of_day:
+            self._alarms[tod].discard(blk)
+
+        do_reload = False
+        # add new times of day
+        for tod in times_of_day - old_times:
+            self._check_tz(tod)
+            if tod in self._alarms:
+                self._alarms[tod].add(blk)
+            else:
+                self._alarms[tod] = {blk}
+                if tod not in _SET24:
+                    do_reload = True    # new entry added to timetable
+        self._reversed[blk] = times_of_day
+
+        # cleanup
+        unused = [tod for tod, blkset in self._alarms.items() if not blkset]
+        for tod in unused:
+            del self._alarms[tod]
+            if tod not in _SET24:
+                do_reload = True    # empty entry removed from the timetable
+        if do_reload:
+            self._do_reload.set()
+
+    async def _cron_daemon(self) -> t.NoReturn:
+        """Recalculate registered blocks according to the schedule."""
+        overhead = _TT_OK   # initial value, will be adjusted
+                            # the sleeptime is reduced by this value
+        reset_flag = False
+        reload_flag = True      # reload will also initialize the index
+        short_sleep = False     # alternative sleep function used => do not compute overhead
+        while True:
+            if reload_flag:
+                timetable = sorted(_SET24.union(self._alarms))
+                tlen = len(timetable)
+                self.log_debug1("time schedule reloaded")
+                index = None
+                reload_flag = False
+
+            nowdt = self.dtnow()
+            nowt = nowdt.time()
+            if index is None:
+                # reload is set before entering the loop -> "tlen" gets initialized
+                # pylint: disable-next=possibly-used-before-assignment
+                index = bisect.bisect_left(timetable, nowt) % tlen
+            wakeup = timetable[index]
+            self.log_debug1("wakeup time: %s", wakeup)
+
+            # sleep until the wakeup time:
+            # step 0 - compute the delay until wakeup time
+            #        - sleep
+            # step 1 - check the current time, adjust overhead estimate,
+            #            A: finish if the time is correct, or
+            #            B: add a tiny sleep if woken up too early, because
+            #               continuing before wakeup time is not acceptable
+            #            C: do a reset if the time is way off
+            # step 2 - check time after 1B,
+            #            A: finish if the time is correct
+            #            B: do a reset otherwise
+            for step in range(3):
+                # datetime.time does not support time arithmetic
+                sleeptime = (SEC_PER_HOUR*(wakeup.hour - nowt.hour)
+                    + SEC_PER_MIN*(wakeup.minute - nowt.minute)
+                    + (wakeup.second - nowt.second)
+                    + (wakeup.microsecond - nowt.microsecond)/ 1_000_000.0)
+                if nowt.hour == 23 and wakeup.hour == 0:
+                    # wrap around midnight (relying on hourly wakeups in SET24)
+                    sleeptime += SEC_PER_DAY
+                # sleeptime: negative = after the alarm time; positive = before the alarm time
+                if step == 0:
+                    self.log_debug2("sleep until wakeup: %.3f sec", sleeptime)
+                if step >= 1 or sleeptime < 0:
+                    diff = abs(sleeptime)
+                    if get_debug_level() >= 2:
+                        msg = 'BEFORE' if sleeptime > 0 else 'after'
+                        self.log_debug(
+                            "step %d, diff %.2f ms %s, estimated overhead: %.2f ms",
+                            step, 1000*diff, msg, 1000*overhead)
+                    if diff > _TT_WARNING:
+                        self.log_warning(
+                            "expected time: %s, current time: %s, diff: %.2f ms.",
+                            wakeup, nowt, 1000*diff)
+                    if (step == 2 and sleeptime > 0) or diff > _TT_ERROR:
+                        reset_flag = True
+                    if reset_flag:
+                        break
+                    if step == 1 and not short_sleep and not -_TT_OK <= sleeptime <= 0:
+                        overhead -= (sleeptime + _TT_OK/2) / 2      # average of new and old
+                    if sleeptime <= 0:
+                        break
+                    if get_debug_level() >= 2:
+                        self.log_debug("additional sleep %.2f ms", 1000*sleeptime)
+
+                if sleeptime == 0.0:
+                    pass    # how likely is this?
+                elif sleeptime <= _SYNC_SLEEP:
+                    short_sleep = True
+                    # breaking the asyncio rules for max time tracking accuracy:
+                    # doing a blocking sleep, but only for a fraction of a millisecond
+                    time.sleep(sleeptime)
+                elif sleeptime <= overhead:
+                    short_sleep = True
+                    await asyncio.sleep(sleeptime)
+                else:
+                    short_sleep = False
+                    try:
+                        async with asyncio.timeout(sleeptime - overhead):
+                            await self._do_reload.wait()
+                    except TimeoutError:
+                        pass
+                    else:
+                        self._do_reload.clear()
+                        reload_flag = True
+                        break
+                nowdt = self.dtnow()
+                nowt = nowdt.time()
+
+            if reset_flag:
+                # DST begin/end or other computer clock related reason
+                if (not self._utc
+                        and nowdt.isoweekday() >= 6
+                        and abs(diff - SEC_PER_HOUR) <= _TT_ERROR
+                        ):
+                    self.log_warning("Apparently a DST (summer time) clock change has occured.")
+                self.log_warning(
+                    "Resetting due to a time tracking problem. "
+                    + "Notifying all registered blocks.")
+                # .rz_cron_event() may alter the dict we are iterating over
+                for blk in list(self._reversed):    # all blocks
+                    assert hasattr(blk, 'rz_cron_event')
+                    blk.rz_cron_event(nowdt)
+                index = None
+                reset_flag = False
+                continue
+            if reload_flag:
+                continue
+
+            if wakeup in self._alarms:
+                # .rz_cron_event() may alter the set we are iterating over
+                block_list = list(self._alarms[wakeup])
+                if get_debug_level() >= 1:
+                    self.log_debug(
+                        "Notifying blocks: %s", ", ".join(blk.name for blk in block_list))
+                for blk in block_list:
+                    assert hasattr(blk, 'rz_cron_event')
+                    blk.rz_cron_event(nowdt)
+            index = (index + 1) % tlen
+
+    def _event__get_config(self, _edata: EventData) -> dict[str, dict[str, list[str]]]:
+        """Return the internal scheduling data for debugging or monitoring."""
+        return {
+            'alarms': {
+                str(recalc_time): sorted(blk.name for blk in blk_set)
+                for recalc_time, blk_set in self._alarms.items()},
+            'blocks': {blk.name: sorted(str(recalc_time) for recalc_time in times_set)
+                for blk, times_set in self._reversed.items()},
+            }

redzed/debug.py

@@ -0,0 +1,86 @@
+"""
+Debug level.
+"""
+from __future__ import annotations
+
+__all__ = ['get_debug_level', 'set_debug_level']
+
+import logging
+import os
+
+from . import circuit
+
+_logger = logging.getLogger(__package__)
+_debug_handler: logging.StreamHandler|None = None
+
+
+class _CircuitTimeFormatter(logging.Formatter):
+    """Formatter for debug level 3."""
+    def format(self, record: logging.LogRecord) -> str:
+        msg = super().format(record)
+        if get_debug_level() >= 3:
+            msg = f"{circuit.get_circuit().runtime():.03f} {msg}"
+        return msg
+
+
+class _DebugLevel:
+    """
+    Global debug level.
+
+    The initial level is set according to the environment variable REDZED_DEBUG.
+    """
+
+    def __init__(self) -> None:
+        self._level = -1    # make sure the set_level's core will run
+        self.set_level(self._get_level_from_env())
+
+    def _get_level_from_env(self) -> int:
+        try:
+            level = os.environ['REDZED_DEBUG']
+        except KeyError:
+            return 0
+        level = level.strip()
+        if not level:
+            return 0
+        if level in {'0', '1', '2', '3'}:
+            return int(level)
+        _logger.warning(
+            "Envvar 'REDZED_DEBUG' should be: 0 (disabled), 1 (normal), "
+            + "2 (verbose) or 3 (verbose with circuit timestamps)")
+        _logger.warning("Ignoring REDZED_DEBUG='%s'. Please use a correct value.", level)
+        return 0
+
+    def get_level(self) -> int:
+        return self._level
+
+    def set_level(self, level: int) -> None:
+        """Set debug level."""
+        global _debug_handler       # pylint: disable=global-statement
+
+        if not isinstance(level, int):
+            raise TypeError(f"Expected an integer, got {level!r}")
+        if level == self._level:
+            return
+        if not 0 <= level <= 3:
+            raise ValueError(f"Debug level must be an integer 0 to 3, but got {level}")
+        # self._level is -1 on initial call
+        if self._level >= 0:
+            _logger.debug("Debug level: %d -> %d", self._level, level)
+        elif level > 0:
+            _logger.debug("Debug level: %d", level)
+        self._level = level
+        if level == 0:
+            if _debug_handler is not None:
+                _logger.removeHandler(_debug_handler)
+                _debug_handler = None
+            _logger.setLevel(logging.WARNING)
+        elif not _logger.hasHandlers() and _debug_handler is None:
+            _logger.addHandler(_debug_handler := logging.StreamHandler())
+            _debug_handler.setFormatter(_CircuitTimeFormatter("%(levelname)s - %(message)s"))
+            _logger.setLevel(logging.DEBUG)
+
+
+_global_debug_level = _DebugLevel()
+
+get_debug_level = _global_debug_level.get_level
+set_debug_level = _global_debug_level.set_level

redzed/formula_trigger.py

@@ -0,0 +1,205 @@
+"""
+Formulas and Triggers.
+- - - - - -
+Part of the redzed package.
+Docs: https://redzed.readthedocs.io/en/latest/
+Project home: https://github.com/xitop/redzed/
+"""
+from __future__ import annotations
+
+__all__ = ['Formula', 'formula', 'Trigger', 'triggered']
+
+from collections.abc import Callable
+import inspect
+import logging
+import typing as t
+
+from . import base_block
+from . import block
+from . import circuit
+from .debug import get_debug_level
+from .undef import UNDEF
+from .utils import func_call_string
+
+_logger = logging.getLogger(__package__)
+
+
+class _ExtFunction:
+    """
+    Manage calls to a function associated with a Trigger or a Formula.
+    """
+
+    def __init__(self, func: Callable[..., t.Any], owner: Formula|Trigger) -> None:
+        """Check if the function's signature is compatible."""
+        self._owner = owner
+        self._func = func
+        self._parameters: list[str] = []
+        self._inputs: list[str|block.Block|Formula] = []
+            # names (strings) must be resolved to objects before start
+        arglist = []
+        Param = inspect.Parameter
+        try:
+            for name, param in inspect.signature(func).parameters.items():
+                # support of positional-only arguments is possible,
+                # but the benefit would be minimal
+                if param.kind not in [Param.POSITIONAL_OR_KEYWORD, Param.KEYWORD_ONLY]:
+                    raise ValueError(
+                        "Function takes *args or **kwargs or positional-only arguments")
+                self._parameters.append(name)
+                if (default := param.default) is Param.empty:
+                    self._inputs.append(name)
+                    arglist.append(name)
+                else:
+                    self._inputs.append(default)
+                    if isinstance(default, str):
+                        arglist.append(f"{name}='{default}'")
+                    elif isinstance(default, (block.Block, Formula)):
+                        arglist.append(f"{name}='{default.name}'")
+                    else:
+                        raise ValueError(
+                            f"The default value in '{name}={default!r}' "
+                            + "does not specify a circuit block")
+            if not arglist:
+                raise ValueError("Function does take any arguments")
+        except ValueError as inspect_error:
+            # Re-raise with more descriptive message and with the original message as a note.
+            # The owner is not initialized yet, so do not try to print e.g. its name.
+            exc = ValueError(f"{owner.type_name} cannot accept function {func.__qualname__}()")
+            exc.add_note(inspect_error.args[0])
+            raise exc from None
+        self.signature = f"{self._func.__name__}({', '.join(arglist)})"
+
+    def resolve_names(self) -> list[block.Block|Formula]:
+        """Resolve names to block or formula objects."""
+        resolve_name = self._owner.circuit.resolve_name
+        self._inputs = [resolve_name(ref) for ref in self._inputs]
+        return t.cast(list[block.Block|Formula], self._inputs)
+
+    def run_function(self) -> t.Any:
+        """Run with output values of referenced blocks."""
+        # union-attr: after pre-init the _inputs does not contain strings
+        kwargs = dict(zip(
+            self._parameters,
+            (blk.get() for blk in self._inputs),    # type: ignore[union-attr]
+            strict=True))
+        if UNDEF in kwargs.values():
+            assert self._owner.circuit.get_state() < circuit.CircuitState.RUNNING
+            if get_debug_level() >= 2:
+                undef = next(iter(param for param, value in kwargs.items() if value is UNDEF))
+                _logger.debug(
+                    "%s: NOT calling the function, because '%s' is UNDEF", self._owner, undef)
+            return UNDEF
+        if get_debug_level() >= 1:
+            _logger.debug(
+                "%s: Calling %s", self._owner, func_call_string(self._func, (), kwargs))
+        try:
+            return self._func(**kwargs)
+        except Exception as err:
+            err.add_note(f"Failed function call originated from {self._owner}")
+            self._owner.circuit.abort(err)
+            raise
+
+
+# Triggers do not have a name nor an output.
+@t.final
+class Trigger:
+    """
+    A circuit item monitoring output changes of selected blocks.
+    """
+    def __init__(self, func: Callable[..., t.Any]) -> None:
+        self._ext_func = _ExtFunction(func, owner=self)
+        self._str = f"<{self.type_name} for {self._ext_func.signature}>"
+        self.circuit = circuit.get_circuit()
+        self.circuit.rz_add_item(self)
+        self._enabled = False
+
+    def __str__(self) -> str:
+        return self._str
+
+    # for compatibility with Blocks and Formulas
+    @property
+    def type_name(self) -> str:
+        return type(self).__name__
+
+    def rz_pre_init(self) -> None:
+        for inp in self._ext_func.resolve_names():
+            inp.rz_add_trigger(self)
+
+    def run(self) -> None:
+        if self._enabled:
+            self._ext_func.run_function()
+
+    def rz_start(self) -> None:
+        self._enabled = True
+        self.run()
+
+    def rz_stop(self) -> None:
+        self._enabled = False
+
+
+_FUNC = t.TypeVar("_FUNC", bound=Callable[..., t.Any])
+def triggered(func: _FUNC) -> _FUNC:
+    """
+    @triggered adds a trigger to a function.
+
+    The function *func* itself it not changed.
+
+    All parameters of the decorated function refer to blocks with
+    the same name. When the output of any of those block changes
+    and none of them is UNDEF, the function will be called
+    with corresponding output values passed as arguments.
+    """
+    Trigger(func)
+    return func
+
+
+@t.final
+class Formula(base_block.BlockOrFormula):
+    """
+    A block with its output computed from other blocks` outputs.
+
+    The output is computed on demand with a provided function.
+    The function should be a pure function, i.e. without side effects.
+
+    The most convenient way to create a Formula block is the
+    @formula decorator.
+    """
+    def __init__(self, *args, func: Callable[..., t.Any], **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+        self._ext_func = _ExtFunction(func, self)
+        self._evaluate_active = False
+
+    def rz_pre_init(self) -> None:
+        for inp in self._ext_func.resolve_names():
+            inp.rz_add_formula(self)
+
+    def rz_start(self) -> None:
+        self.evaluate()
+
+    def evaluate(self) -> set[Trigger]:
+        """
+        Evaluate this formula and dependent formulas.
+
+        Return a set of affected triggers.
+        """
+        if self._evaluate_active:
+            raise RuntimeError(f"{self}: detected a dependency loop")
+        result = self._ext_func.run_function()
+        if result is UNDEF or not self._set_output(result):
+            return set()
+        triggers = self._dependent_triggers.copy()
+        self._evaluate_active = True
+        for frm in self._dependent_formulas:
+            triggers |= frm.evaluate()
+        self._evaluate_active = False
+        return triggers
+
+def formula(name: str, *args, **kwargs) -> Callable[[_FUNC], _FUNC]:
+    """@formula() creates a Formula block with the decorated function."""
+    if 'func' in kwargs:
+        # Argument func=... will be supplied by us
+        raise TypeError("@formula() got an unexpected keyword argument 'func='")
+    def decorator(func: _FUNC) -> _FUNC:
+        Formula(name, *args, func=func, **kwargs)
+        return func
+    return decorator