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

redzed/cron_service.py

@@ -3,8 +3,8 @@ 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.
-
 - - - - - -
+Part of the redzed package.
 Docs: https://redzed.readthedocs.io/en/latest/
 Home: https://github.com/xitop/redzed/
 """
@@ -12,23 +12,41 @@ from __future__ import annotations
 
 import asyncio
 import bisect
+from collections import deque
 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
+# time tracking settings (in seconds)
+_TT_OVERHEAD = 0.001    # asyncio sleep overhead estimation; real value will be measured
+_TT_WARNING = 0.2       # timing difference threshold for a warning message
+_TT_ERROR = 2.5         # timing difference threshold for a reset
+
+# hourly wake ups for precise time tracking and early detection of DST changes
+_SET24H = frozenset(dt.time(hour, 0, 0) for hour in range(24))
 
-# 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))
+
+def _wait_time(t1: dt.time, t2: dt.time) -> float:
+    """
+    Return seconds from *t1* to *t2* on a 24 hour clock.
+
+    The result is always between -1 and 23 hours (in seconds).
+    Positive values are normal wait times (when *t2* is after *t1*).
+    Negative values correspond to delays after a missed event
+    (when *t2* is less than 1 hour before *t1*).
+    """
+    # datetime.time does not support time arithmetic
+    diff = (SEC_PER_HOUR*(t2.hour - t1.hour)
+        + SEC_PER_MIN*(t2.minute - t1.minute)
+        + (t2.second - t1.second)
+        + (t2.microsecond - t1.microsecond) / 1_000_000.0)
+    if -SEC_PER_HOUR < diff <= 23 * SEC_PER_HOUR:
+        return diff
+    return diff + SEC_PER_DAY if diff < 0 else diff - SEC_PER_DAY
 
 
 class Cron(Block):
@@ -44,7 +62,10 @@ class Cron(Block):
     def __init__(self, *args, utc: bool, **kwargs) -> None:
         super().__init__(*args, **kwargs)
         self._utc = bool(utc)
-        self._alarms: dict[dt.time, set[Block]] = {}
+        self._alarms: dict[dt.time, set[Block]] = {tod: set() for tod in _SET24H}
+        self._timetable: list[dt.time] = sorted(_SET24H)
+            # timetable = sorted list (for bisection) of wake-up times (i.e. _alarms keys)
+        self._tt_len = 24
         self._reversed: dict[Block, set[dt.time]] = {}
         self._do_reload = asyncio.Event()
 
@@ -69,144 +90,137 @@ class Cron(Block):
             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.
-        """
+        """Add a block to be activated at given times or update its schedule."""
         if not hasattr(blk, 'rz_cron_event'):
             raise TypeError(f"{blk} is not compatible with the cron service")
+        for tod in times_of_day:
+            self._check_tz(tod)
+        self.log_debug2("Got a new schedule for %s", blk)
+        times_of_day = set(times_of_day)
 
-        times_of_day = set(times_of_day) # make a set, make a copy
-        # remove old times of day
+        # remove old times of day; it is not necessary to notify the main loop
         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
+        do_reload = False
         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
+                # new entry added to timetable; the main loop must be notified
+                do_reload = True
         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()
+        # cleanup
+        for tod in [
+                tod for tod, blks in self._alarms.items() if tod not in _SET24H and not blks]:
+            del self._alarms[tod]
+
+        self._timetable = sorted(self._alarms)
+        self._tt_len = len(self._timetable)
+
 
     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
+        overhead = _TT_OVERHEAD       # an estimate to start with
+        measured_overheads: deque[float] = deque(maxlen=8)
+        prev_sleeptime: float
+        long_sleep: bool
+        wakeup: dt.time|None = None
 
+        while True:
             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 wakeup is None or self._do_reload.is_set():
+                index = bisect.bisect_left(self._timetable, nowt)
+                next_wakeup = self._timetable[index % self._tt_len]
+                # next_wakeup is new and wakeup was not processed yet,
+                # all we need is to select which one comes first.
+                if wakeup is None \
+                        or next_wakeup != wakeup and _wait_time(next_wakeup, wakeup) > 0:
+                    wakeup = next_wakeup
+                # else: the current wakeup is confirmed
+                self._do_reload.clear()
+                self.log_debug1("wake-up time after reload: %s", wakeup)
+            else:
+                # return the next entry (in circular manner)
+                index = bisect.bisect_right(self._timetable, wakeup)
+                wakeup = self._timetable[index % self._tt_len]
+                self.log_debug1("wake-up time: %s", wakeup)
+
+            # sleep until the wake-up time:
+            #   step 0: main sleep
+            #       compute the delay until wake-up time and sleep
+            #   steps 1 and 2: fine adjustment
+            #       check the current time, adjust overhead estimate and
+            #           - finish if the time is correct, or
+            #           - add a tiny sleep if woken up too early, because
+            #             that is not acceptable, or
+            #           - do a reset if the time is way off
+            #   steps 3 and 4: safety net
+            #       like above, just for the case the computer clock
+            #       does something unexpected
+            for step in range(5):
+                sleeptime = _wait_time(nowt, wakeup)    # negative = we are late
+                debug2 = get_debug_level() >= 2
                 if step == 0:
-                    self.log_debug2("sleep until wakeup: %.3f sec", sleeptime)
-                if step >= 1 or sleeptime < 0:
+                    if debug2:
+                        self.log_debug("sleep until wake up: %.3f sec", sleeptime)
+                else:
                     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)
+                    after = sleeptime <= 0.0
                     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:
+                            "expected time: %s, current time: %s, diff: %.1f sec %s",
+                            wakeup, nowt, diff, 'after' if after else 'BEFORE')
+                    elif debug2:
+                        self.log_debug(
+                            "iteration %d, diff %.2f ms %s",
+                            step, 1000*diff, 'after' if after else 'BEFORE')
+                    # prev_sleeptime and long_sleep has been set in previous step
+                    # pylint: disable=used-before-assignment
+                    if diff > _TT_ERROR or sleeptime > prev_sleeptime or step == 4:
+                        # something is wrong with the computer clock
                         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:
+                    if long_sleep:
+                        saved = overhead
+                        measured_overheads.append(overhead - sleeptime)
+                        # Using smallest overhead recently measured, because to be late
+                        # by a tiny amount is much better than to wake up early by a tiny
+                        # amount. The latter case must be corrected by another sleep.
+                        overhead = min(measured_overheads)
+                        if debug2 and overhead != saved:
+                            self.log_debug("estimated overhead >= %.2f ms", 1000*overhead)
+                    if after:
                         break
-                    if get_debug_level() >= 2:
+                    if debug2:
                         self.log_debug("additional sleep %.2f ms", 1000*sleeptime)
+                prev_sleeptime = 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
+                if (long_sleep := sleeptime > overhead):
                     try:
                         async with asyncio.timeout(sleeptime - overhead):
                             await self._do_reload.wait()
                     except TimeoutError:
-                        pass
+                        pass    # no reload request
                     else:
-                        self._do_reload.clear()
-                        reload_flag = True
-                        break
+                        break   # reload request arrived
+                elif sleeptime > 0.0:
+                    await asyncio.sleep(sleeptime)
                 nowdt = self.dtnow()
                 nowt = nowdt.time()
+            # --- end for loop ---
 
             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
-                        ):
+                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. "
@@ -215,29 +229,29 @@ class Cron(Block):
                 for blk in list(self._reversed):    # all blocks
                     assert hasattr(blk, 'rz_cron_event')
                     blk.rz_cron_event(nowdt)
-                index = None
                 reset_flag = False
+                wakeup = None
                 continue
-            if reload_flag:
+            if self._do_reload.is_set():
                 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
+            if wakeup not in self._alarms:
+                continue    # entry removed in the meantime
+            # .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 block(s): %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)
 
     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()},
+                str(tod): sorted(blk.name for blk in blks)
+                for tod, blks in self._alarms.items() if blks},
+            'blocks': {blk.name: sorted(str(tod) for tod in tods)
+                for blk, tods in self._reversed.items()},
             }

redzed/debug.py

@@ -1,26 +1,37 @@
 """
-Debug level.
+Debug levels.
+- - - - - -
+Part of the redzed package.
+Docs: https://redzed.readthedocs.io/en/latest/
+Home: https://github.com/xitop/redzed/
 """
 from __future__ import annotations
 
-__all__ = ['get_debug_level', 'set_debug_level']
-
 import logging
 import os
 
 from . import circuit
 
+__all__ = ['get_debug_level', 'set_debug_level']
+
 _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
+def get_level_from_env() -> int|None:
+    if (env_level := os.environ.get('REDZED_DEBUG', '')) == '':
+        return None
+    try:
+        level = int(env_level)
+    except Exception:
+        pass
+    else:
+        if 0 <= level <= 3:
+            return level
+    _logger.warning(
+        "Envvar 'REDZED_DEBUG' should be: 0 (disabled), 1 (normal), "
+        + "2 (verbose) or 3 (verbose with circuit timestamps)")
+    _logger.error("Ignoring REDZED_DEBUG='%s'. Please use a correct value.", env_level)
+    return None
 
 
 class _DebugLevel:
@@ -31,56 +42,62 @@ class _DebugLevel:
     """
 
     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:
+        if (level := get_level_from_env()) is None:
+            level = 0
+        self._level = level
+        _logger.debug("[Logging] Debug level: %d", level)
+
+    @property
+    def level(self) -> int:
         return self._level
 
-    def set_level(self, level: int) -> None:
+    @level.setter
+    def 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 isinstance(level, int):
+            raise TypeError(f"Expected an integer, got {level!r}")
         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)
+        _logger.debug("[Logging] Debug level: %d -> %d", self._level, 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()
+_debug_level = _DebugLevel()
+
+
+def get_debug_level():
+    """Get the debug level."""
+    return _debug_level.level
 
-get_debug_level = _global_debug_level.get_level
-set_debug_level = _global_debug_level.set_level
+
+def set_debug_level(level):
+    """
+    Set the debug level.
+
+    Also make sure debug messages will be logged or printed.
+    For this purpose, if there is no handler, add an own stream handler.
+    """
+    _debug_level.level = level
+    if circuit.get_circuit().get_state() in [
+            circuit.CircuitState.UNDER_CONSTRUCTION, circuit.CircuitState.CLOSED]:
+        return
+    if level > 0:
+        if not _logger.hasHandlers():
+            _logger.addHandler(logging.StreamHandler())
+            _logger.propagate = False
+        _logger.setLevel(logging.DEBUG)
+    else:
+        _logger.setLevel(logging.NOTSET if _logger.propagate else logging.INFO)
+
+
+class _CircuitTimeFilter(logging.Filter):
+    """Filter adding timestamsps in debug level 3."""
+    def filter(self, record: logging.LogRecord) -> bool:
+        if _debug_level.level >= 3 and isinstance(record.msg, str):
+            record.msg = f"{circuit.get_circuit().runtime():.03f} {record.msg}"
+        return True
+
+
+_logger.addFilter(_CircuitTimeFilter())

redzed/formula_trigger.py

@@ -194,12 +194,8 @@ class Formula(base_block.BlockOrFormula):
         self._evaluate_active = False
         return triggers
 
-def formula(name: str, *args, **kwargs) -> Callable[[_FUNC], _FUNC]:
+def formula(func: _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
+    comment = '' if func.__doc__ is None else inspect.cleandoc(func.__doc__).partition('\n')[0]
+    Formula(func.__name__, func=func, comment=comment)
+    return func

redzed/initializers.py

@@ -2,8 +2,8 @@
 Block initializers.
 - - - - - -
 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
 
@@ -18,7 +18,7 @@ import typing as t
 
 from . import block
 from .undef import UNDEF, UndefType
-from .utils import check_async_func, time_period
+from .utils import time_period
 
 
 _LONG_TIMEOUT = 60      # threshold for a "long timeout" debug message
@@ -225,19 +225,18 @@ class InitTask(AsyncInitializer):
 
     def __init__(
             self,
-            coro_func: Callable[..., Awaitable[t.Any]],
+            aw_func: Callable[..., Awaitable[t.Any]],
             *args: t.Any,
             timeout: float|str = 10.0
             ) -> None:
         """Similar to InitFunction, but asynchonous."""
-        check_async_func(coro_func)
         super().__init__(timeout)
-        self._corofunc = coro_func
+        self._aw_func = aw_func
         self._args = args
 
     async def _async_get_init(self) -> t.Any:
         async with asyncio.timeout(self._timeout):
-            return await self._corofunc(*self._args)
+            return await self._aw_func(*self._args)
 
 
 class InitWait(AsyncInitializer):

redzed/signal_shutdown.py

@@ -2,8 +2,8 @@
 Stop the runner with a signal.
 - - - - - -
 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
 
@@ -55,7 +55,7 @@ class TerminatingSignal:
         """A signal handler."""
         # - we need the _threadsafe variant of call_soon
         # - get_running loop() and get_circuit() will succeed,
-        #   because this handler is active only during edzed.run()
+        #   because this handler is active only during redzed.run()
         msg = f"Signal {self._signame!r} caught"
         call_soon = asyncio.get_running_loop().call_soon_threadsafe
         call_soon(_logger.warning, "%s", msg)

redzed/undef.py

@@ -2,8 +2,8 @@
 The UNDEF singleton constant.
 - - - - - -
 Part of the redzed package.
-# 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/
 """
 from __future__ import annotations