redzed 25.12.30__py3-none-any.whl

redzed/blocklib/timedate.py

@@ -0,0 +1,150 @@
+"""
+Periodic events at fixed time/date.
+
+- - - - - -
+Docs: https://edzed.readthedocs.io/en/latest/
+Home: https://github.com/xitop/edzed/
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence, Set
+import datetime as dt
+import typing as t
+
+import redzed
+from . import timeinterval as ti
+from ..cron_service import Cron
+
+
+__all__ = ['TimeDate', 'TimeSpan']
+
+def _get_cron(utc: bool) -> Cron:
+    name = '_cron_utc' if utc else '_cron_local'
+    return t.cast(Cron, redzed.get_circuit().resolve_name(name))
+
+
+_MIDNIGHT = dt.time(0, 0, 0)
+
+
+class _ConfigType(t.TypedDict):
+    times: t.NotRequired[ti.DT_Interval_Type]
+    dates: t.NotRequired[ti.DT_Interval_Type]
+    weekdays: t.NotRequired[Sequence[int]]
+
+
+class TimeDate(redzed.Block):
+    """
+    Block for periodic events at given time/date.
+    """
+
+    def __init__(self, *args, utc: bool = False, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+        self._cron = _get_cron(utc)
+        self._times: ti.TimeInterval | None = None
+        self._dates: ti.DateInterval | None = None
+        self._weekdays: Set[int] | None = None
+
+    def _reconfig(self, config: _ConfigType) -> None:
+        """Reconfigure the block."""
+        if extra := config.keys() - {'times', 'dates', 'weekdays'}:
+            raise ValueError(f"{self}: Unexpected key '{next(iter(extra))}' in configuration")
+        times = config.get('times', None)
+        dates = config.get('dates', None)
+        weekdays = config.get('weekdays', None)
+        if all(cfg is None for cfg in [times, dates, weekdays]):
+            raise ValueError("Empty configuration data")
+        self._times = None if times is None else ti.TimeInterval(times)
+        self._dates = None if dates is None else ti.DateInterval(dates)
+        if weekdays is None:
+            self._weekdays = None
+        else:
+            if not all(0 <= x <= 7 for x in weekdays):
+                raise ValueError(
+                    "Only numbers 0 or 7 (Sun), 1 (Mon), ... 6(Sat) are accepted as weekdays")
+            self._weekdays = frozenset(7 if x == 0 else x for x in weekdays)
+
+        endpoints = self._times.range_endpoints() if self._times is not None else set()
+        if self._dates or self._weekdays:
+            endpoints.add(_MIDNIGHT)
+        self._cron.set_schedule(self, endpoints)
+        self.rz_cron_event(self._cron.dtnow())
+
+    def rz_init(self, value: _ConfigType, /) -> None:
+        if not isinstance(value, Mapping):
+            raise TypeError(
+                "Initialization value must be a dict (mapping), "
+                + f"but got {type(value).__name__}")
+        self._reconfig(value)
+
+    def rz_init_default(self) -> None:
+        self._times = None
+        self._dates = None
+        self._weekdays = frozenset()
+        self._set_output(False)
+
+    def _event_reconfig(self, edata: redzed.EventData) -> None:
+        self._reconfig(edata['evalue'])
+
+    def _event__get_config(self, _edata: redzed.EventData) -> dict[str, Sequence|None]:
+        # _get_config event == _get_state event == rz_export_state function
+        return self.rz_export_state()
+
+    def rz_cron_event(self, now: dt.datetime) -> None:
+        """Update the output."""
+        self._set_output(
+            (self._weekdays is None or now.isoweekday() in self._weekdays)
+            and (self._times is None or now.time() in self._times)
+            and (self._dates is None
+                 or dt.date(ti.DUMMY_YEAR, now.month, now.day) in self._dates)
+            )
+
+    def rz_export_state(self) -> dict[str, Sequence|None]:
+        return {
+            'times': None if self._times is None else self._times.as_list(),
+            'dates': None if self._dates is None else self._dates.as_list(),
+            'weekdays': None if self._weekdays is None else sorted(self._weekdays),
+        }
+
+    rz_restore_state = rz_init
+
+
+class TimeSpan(redzed.Block):
+    """
+    Block active between start and stop time/date.
+    """
+
+    def __init__(self, *args, utc: bool = False, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._cron = _get_cron(utc)
+        self._span: ti.DateTimeInterval
+
+    def _reconfig(self, config: ti.DT_Interval_Type) -> None:
+        """Reconfigure the block."""
+        self._span = ti.DateTimeInterval(config)
+        now = self._cron.dtnow()
+        now_date = now.date()
+        endpoints = {ep.time() for ep in self._span.range_endpoints() if ep.date() >= now_date}
+        self._cron.set_schedule(self, endpoints)
+        self.rz_cron_event(now)
+
+    rz_init = _reconfig
+
+    def rz_init_default(self) -> None:
+        self._reconfig([])
+
+    def _event_reconfig(self, edata: redzed.EventData) -> None:
+        self._reconfig(edata['evalue'])
+
+    def _event__get_config(self, _edata: redzed.EventData) -> ti.DT_Interval_Type:
+        # _get_config event == _get_state event == rz_export_state function
+        return self.rz_export_state()
+
+    def rz_cron_event(self, now: dt.datetime) -> None:
+        """Update the output."""
+        self._set_output(now in self._span)
+
+    def rz_export_state(self) -> ti.DT_Interval_Type:
+        return self._span.as_list()
+
+    rz_restore_state = _reconfig

redzed/blocklib/timeinterval.py

@@ -0,0 +1,192 @@
+"""
+This module defines time/date intervals.
+
+It is built on top of the datetime (dt) module:
+    - time of day -> dt.time
+    - date without a year -> dt.date with year set to a dummy value
+    - date -> dt.date
+    - full date+time -> dt.datetime
+
+Intervals use those objects as endpoints:
+    - TimeInterval defines time intervals within a day,
+    - DateInterval defines periods in a year.
+    - DateTimeInterval defines non-recurring intervals.
+
+All intervals support the operation "value in interval".
+"""
+from __future__ import annotations
+
+from collections.abc import Sequence
+import datetime as dt
+import typing as t
+
+# any sequence when importing, always a nested list when exporting
+DT_Interval_Type = Sequence[Sequence[Sequence[int]]]
+
+# endpoint type
+_DateTimeType = t.TypeVar("_DateTimeType", dt.time, dt.date, dt.datetime)
+
+
+_DT_ATTRS = "year month day hour minute second microsecond".split()
+
+class _Interval(t.Generic[_DateTimeType]):
+    """
+    The common part of Date/Time Intervals.
+
+    Warning: time/date intervals do not follow the strict mathematical
+    interval definition.
+    """
+
+    # https://en.wikipedia.org/wiki/Interval_(mathematics)#Definitions_and_terminology
+    # the subintervals are always left-closed
+    _RCLOSED_INTERVAL: bool     # are the subintervals right-closed?
+    _EXPORT_ATTRS: Sequence[str]
+
+    @staticmethod
+    def _convert(seq: Sequence[int]) -> _DateTimeType:
+        raise NotImplementedError
+
+    def convert(self, seq: Sequence[int]) -> _DateTimeType:
+        try:
+            return self._convert(seq)
+        except Exception as err:
+            err.add_note(f"Input value was: {seq!r}")
+            raise
+
+    def __init__(self, ivalue: DT_Interval_Type):
+        """
+        Argument ivalue must be a sequence of ranges:
+            _Interval([subinterval1, subinterval2, ...])
+        where each range (subinterval) is a pair of endpoints [begin, end].
+
+        After splitting into endpoints, each value is converted
+        to time/date according to the actual interval type.
+        """
+        self._interval: list[list[_DateTimeType]]
+        if not isinstance(ivalue, Sequence) or isinstance(ivalue, str):
+            raise TypeError(f"Unsupported argument type: {type(ivalue).__name__}")
+        self._interval = sorted(self._parse_range(subint) for subint in ivalue)
+
+    def _parse_range(self, rng: Sequence[Sequence[int]]) -> list[_DateTimeType]:
+        """Parse: [begin, end]"""
+        if not isinstance(rng, Sequence) or isinstance(rng, str):
+            raise TypeError(
+                f"Invalid range type. Expected was a pair [begin, and], got {rng!r}")
+        if (length := len(rng)) != 2:
+            raise ValueError(f"A range must have 2 endpoints, got range with {length}: {rng!r}")
+        return [self.convert(rng[0]), self.convert(rng[1])]
+
+    def range_endpoints(self) -> set[_DateTimeType]:
+        """return all unique range start and stop values."""
+        enpoints = set()
+        for start, stop in self._interval:
+            enpoints.add(start)
+            enpoints.add(stop)
+        return enpoints
+
+    @staticmethod
+    def _cmp_open(low: _DateTimeType, item: _DateTimeType, high: _DateTimeType) -> bool:
+        """
+        The ranges are left-closed and right-open intervals, i.e.
+        value is in interval if and only if start <= value < stop
+        """
+        if low < high:
+            return low <= item < high
+        # low <= item < MAX or MIN <= item < high
+        return low <= item or item < high
+
+    @staticmethod
+    def _cmp_closed(low: _DateTimeType, item: _DateTimeType, high: _DateTimeType) -> bool:
+        """
+        The ranges are closed intervals, i.e.
+        value is in interval if and only if start <= value <= stop
+        """
+        if low <= high:
+            return low <= item <= high
+        return low <= item or item <= high
+
+    def _cmp(self, *args: _DateTimeType) -> bool:
+        return (self._cmp_closed if self._RCLOSED_INTERVAL else self._cmp_open)(*args)
+
+    def __contains__(self, item: _DateTimeType) -> bool:
+        return any(self._cmp(low, item, high) for low, high in self._interval)
+
+    @classmethod
+    def _export_dt(cls, dt_object: _DateTimeType) -> list[int]:
+        """Export a date/time object."""
+        return [getattr(dt_object, attr) for attr in cls._EXPORT_ATTRS]
+
+    def as_list(self) -> DT_Interval_Type:
+        """
+        Return the intervals as a nested list of integers.
+
+        The output is a list of endpoint pairs. Each endpoint is a list
+        of integers. The output is suitable as an input argument.
+        """
+        return [
+            [self._export_dt(start), self._export_dt(stop)]
+            for start, stop in self._interval]
+
+
+class TimeInterval(_Interval[dt.time]):
+    """
+    List of time ranges.
+
+    The whole day is 00:00 - 00:00.
+    """
+
+    _RCLOSED_INTERVAL = False
+    _EXPORT_ATTRS = _DT_ATTRS[3:]
+
+    @staticmethod
+    def _convert(seq: Sequence[int]) -> dt.time:
+        """[hour, minute, second=0, microsecond=0] -> time of day"""
+        if not 2 <= len(seq) <= 4:
+            raise ValueError(
+                f"{seq} not in expected format: [hour, minute=0, second=0, µs=0]")
+        # mypy is overlooking that the seq cannot have more than 4 items
+        return dt.time(*seq, tzinfo=None)      # type: ignore[misc, arg-type]
+
+
+DUMMY_YEAR = 404
+# 404 is a leap year (allows Feb 29) and is not similar
+# to anything related to modern date values
+
+class DateInterval(_Interval[dt.date]):
+    """
+    List of date ranges and single dates.
+    """
+
+    _RCLOSED_INTERVAL = True
+    _EXPORT_ATTRS = _DT_ATTRS[1:3]
+
+    @staticmethod
+    def _convert(seq: Sequence[int]) -> dt.date:
+        """[month, day] -> date (without year)"""
+        if len(seq) != 2:
+            raise ValueError(f"{seq} not in expected format: [month, day]")
+        return dt.date(DUMMY_YEAR, *seq)
+
+
+class DateTimeInterval(_Interval[dt.datetime]):
+    """
+    List of datetime ranges.
+    """
+
+    _RCLOSED_INTERVAL = False
+    _EXPORT_ATTRS = _DT_ATTRS
+
+    @staticmethod
+    def _cmp_open(low: dt.datetime, item: dt.datetime, high: dt.datetime) -> bool:
+        """Compare function for non-recurring intervals."""
+        return low <= item < high
+
+    @staticmethod
+    def _convert(seq: Sequence[int]) -> dt.datetime:
+        """[year, month, day, hour, minute, second=0, microsecond=0] -> datetime"""
+        if not 5 <= len(seq) <= 7:
+            raise ValueError(
+                f"{seq} not in expected format: "
+                "[year, month, day, hour, minute, second=0, µs=0]")
+        # mypy is overlooking that the time_seq cannot have more than 7 items
+        return dt.datetime(*seq, tzinfo=None)      # type: ignore[misc, arg-type]

redzed/blocklib/timer.py

@@ -0,0 +1,50 @@
+"""
+A timer for general use.
+- - - - - -
+Part of the redzed package.
+Docs: https://redzed.readthedocs.io/en/latest/
+Home: https://github.com/xitop/redzed/
+"""
+from __future__ import annotations
+
+__all__ = ['Timer']
+
+from redzed.utils import time_period
+from .fsm import FSM
+
+
+class Timer(FSM):
+    """
+    A timer.
+    """
+
+    ALL_STATES = ['off', 'on']
+    TIMED_STATES = [
+        ['on', float("inf"), 'off'],
+        ['off', float("inf"), 'on']]
+    EVENTS = [
+        ['start', ..., 'on'],
+        ['stop', ..., 'off'],
+        ['toggle', ['on'], 'off'],
+        ['toggle', ['off'], 'on']]
+
+    def __init__(self, *args, restartable: bool = True, **kwargs) -> None:
+        if 't_period' in kwargs:
+            if ('t_on' in kwargs or 't_off' in kwargs):
+                raise TypeError("t_period and t_on/t_off are mutually exclusive.")
+            period = time_period(kwargs.pop('t_period'))
+            kwargs['t_on'] = kwargs['t_off'] = period / 2
+        super().__init__(*args, **kwargs)
+        if self._t_duration.get('on') == self._t_duration.get('off') == 0.0:
+            raise ValueError(
+                f"{self}: Durations for timer states 'on' and 'off' cannot be both zero")
+        self._restartable = bool(restartable)
+
+    def cond_start(self) -> bool:
+        return self._restartable or self._state != 'on'
+
+    def cond_stop(self) -> bool:
+        return self._restartable or self._state != 'off'
+
+    def _set_output(self, output) -> bool:
+        return super()._set_output(output == 'on')