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

redzed/blocklib/outputs.py

@@ -1,8 +1,9 @@
 """
 Output blocks.
 - - - - - -
-Docs: https://edzed.readthedocs.io/en/latest/
-Home: https://github.com/xitop/edzed/
+Part of the redzed package.
+Docs: https://redzed.readthedocs.io/en/latest/
+Home: https://github.com/xitop/redzed/
 """
 from __future__ import annotations
 
@@ -13,7 +14,8 @@ from collections.abc import Callable, Awaitable
 import typing as t
 
 import redzed
-from redzed.utils import BufferShutDown, cancel_shield, func_call_string, MsgSync, time_period
+from redzed.utils import BufferShutDown, cancel_shield, func_call_string, time_period
+from .validator import _Validate
 
 
 class OutputFunc(redzed.Block):
@@ -28,22 +30,27 @@ class OutputFunc(redzed.Block):
             triggered_by: str|redzed.Block|redzed.Formula|redzed.UndefType = redzed.UNDEF,
             **kwargs) -> None:
         super().__init__(*args, **kwargs)
-        self._stop_value = stop_value
         self._func = func
-        self._parameters: list[tuple[str, bool]] = []    # item: (name, is_required)
+        self._shutdown = False
+        if stop_value is not redzed.UNDEF:
+            @redzed.stop_function
+            def stop_function_():
+                self._event_put({'evalue': stop_value})
+            stop_function_.__qualname__ += self.name
+            stop_function_.__name__ += self.name
         if triggered_by is not redzed.UNDEF:
             @redzed.triggered
             def trigger(value=triggered_by) -> None:
                 self.event('put', value)
 
     def _event_put(self, edata: redzed.EventData) -> t.Any:
-        arg = edata['evalue']
+        evalue = edata['evalue']
         if redzed.get_debug_level() >= 1:
-            self.log_debug("Running %s", func_call_string(self._func, (arg,)))
+            self.log_debug("Running %s", func_call_string(self._func, (evalue,)))
         try:
-            result = self._func(arg)
+            result = self._func(evalue)
         except Exception as err:
-            func_args = func_call_string(self._func, (arg,))
+            func_args = func_call_string(self._func, (evalue,))
             self.log_error("Output function failed; call: %s; error: %r", func_args, err)
             err.add_note(f"Error occurred in function call {func_args}")
             self.circuit.abort(err)
@@ -51,30 +58,64 @@ class OutputFunc(redzed.Block):
         self.log_debug2("output function returned: %r", result)
         return result
 
+    def rz_is_shut_down(self) -> bool:
+        return self._shutdown
+
     def rz_stop(self) -> None:
-        if self._stop_value is not redzed.UNDEF:
-            self._event_put({'evalue': self._stop_value})
+        self._shutdown = True
 
 
-class _Buffer(redzed.Block):
+class _Buffer(_Validate, redzed.Block):
     def __init__(
             self, *args,
             stop_value: t.Any = redzed.UNDEF,
             triggered_by: str|redzed.Block|redzed.Formula|redzed.UndefType = redzed.UNDEF,
             **kwargs) -> None:
         super().__init__(*args, **kwargs)
-        self._stop_value = stop_value
+        self._shutdown = False
+        if stop_value is not redzed.UNDEF:
+            stop_value = self._validate(stop_value)
+            @redzed.stop_function
+            def stop_function_():
+                self.rz_put_value(stop_value)
+            stop_function_.__qualname__ += self.name
+            stop_function_.__name__ += self.name
         if triggered_by is not redzed.UNDEF:
             @redzed.triggered
             def trigger(value=triggered_by) -> None:
                 self.event('put', value)
 
+    def _event_put(self, edata: redzed.EventData) -> None:
+        """Put an item into the queue."""
+        # not aggregating following two lines in order to have a clear traceback
+        evalue = edata['evalue']
+        evalue = self._validate(evalue)
+        self.rz_put_value(evalue)
+
+    def _event__get_size(self, _edata: redzed.EventData) -> int:
+        return self.rz_get_size()
+
+    def rz_is_shut_down(self) -> bool:
+        return self._shutdown
+
+    def rz_stop(self) -> None:
+        self._shutdown = True
+
+    def rz_put_value(self, value: t.Any) -> None:
+        raise NotImplementedError
+
     def rz_get_size(self) -> int:
         raise NotImplementedError
 
     async def rz_buffer_get(self) -> t.Any:
         raise NotImplementedError
 
+    def rz_close(self) -> None:
+        if (size := self.rz_get_size()) == 1:
+            self.log_error("One value was not retrieved from buffer")
+        elif size > 1:
+            self.log_error("%d values were not retrieved from buffer", size)
+
 
 class QueueBuffer(_Buffer):
     """
@@ -92,26 +133,17 @@ class QueueBuffer(_Buffer):
         # Queue.shutdown is available in Python 3.13, but we want to support 3.11+
         self._waiters = 0
 
-    def _event_put(self, edata: redzed.EventData) -> None:
-        """Put an item into the queue."""
-        evalue = edata['evalue']
-        if evalue is redzed.UNDEF:
-            raise ValueError(f"{self}: Cannot put UNDEF into the buffer")
-        self._queue.put_nowait(evalue)
+    def rz_put_value(self, value: t.Any) -> None:
+        self._queue.put_nowait(value)
 
     def rz_get_size(self) -> int:
         """Get the number of items in the buffer."""
         return self._queue.qsize()
 
-    def _event__get_size(self, _edata: redzed.EventData) -> int:
-        return self.rz_get_size()
-
     def rz_stop(self) -> None:
-        # stop_value might be UNDEF
-        self._queue.put_nowait(self._stop_value)
-        # unblock waiters (-1 accounts for the inserted stop value)
-        for _ in range(self._waiters - 1):
-            self._queue.put_nowait(redzed.UNDEF)
+        super().rz_stop()
+        for _ in range(self._waiters):
+            self.rz_put_value(redzed.UNDEF)
 
     async def rz_buffer_get(self) -> t.Any:
         """
@@ -121,7 +153,7 @@ class QueueBuffer(_Buffer):
         After the shutdown drain the queue
         and then raise BufferShutDown to each caller.
         """
-        if self.circuit.after_shutdown() and self._queue.qsize() == 0:
+        if self._shutdown and self._queue.qsize() == 0:
             raise BufferShutDown("The buffer was shut down")
         self._waiters += 1
         try:
@@ -133,10 +165,6 @@ class QueueBuffer(_Buffer):
             raise BufferShutDown("The buffer was shut down")
         return value
 
-    def rz_close(self) -> None:
-        if (size := self._queue.qsize()) > 0:
-            self.log_warning("%d unprocessed item(s) left in the buffer", size)
-
 
 class MemoryBuffer(_Buffer):
     """
@@ -145,64 +173,65 @@ class MemoryBuffer(_Buffer):
 
     def __init__(self, *args, **kwargs) -> None:
         super().__init__(*args, **kwargs)
-        self._cell: MsgSync[t.Any] = MsgSync()
-        self._stop_pending = False
+        # allowed states:
+        #            _shutdown    value   has_value
+        # - has value: False,    not UNDEF, set
+        # - is empty:  False,    UNDEF,     cleared
+        # - draining:  True,     not UNDEF, set
+        # - shut down: True,     UNDEF,     set
+        self._value = redzed.UNDEF
+        self._has_value = asyncio.Event()
 
     def rz_get_size(self) -> int:
         """Get the number of items (0 or 1) in the buffer."""
-        has_data = self._cell.has_data() or self._cell.is_shutdown() and self._stop_pending
+        has_data = self._value is not redzed.UNDEF
         return 1 if has_data else 0
 
-    def _event__get_size(self, _edata: redzed.EventData) -> int:
-        return self.rz_get_size()
-
-    def _event_put(self, edata: redzed.EventData) -> None:
-        """Put an item into the memory cell. Existing value will be overwritten."""
-        self._cell.send(edata['evalue'])
+    def rz_put_value(self, value: t.Any) -> None:
+        if value is redzed.UNDEF:
+            raise ValueError(f"{self}: Cannot put UNDEF into the buffer")
+        self._value = value
+        self._has_value.set()
 
     def rz_stop(self) -> None:
         """Shut down"""
-        self._cell.shutdown()
-        self._stop_pending = self._stop_value is not redzed.UNDEF
+        super().rz_stop()
+        if not self._has_value.is_set():
+            assert self._value is redzed.UNDEF
+            self._has_value.set()   # unblock reader(s)
 
     async def rz_buffer_get(self) -> t.Any:
-        """
-        Remove and return an item from the memory cell.
-
-        When the buffer is empty:
-          - before shutdown wait
-          - after shutdown return the *stop_value* once (if defined),
-            then raise BufferShutDown
-        """
-        try:
-            return await self._cell.recv()
-        except BufferShutDown:
-            if not self._stop_pending:
-                raise
-            self._stop_pending = False
-            return self._stop_value
-
-    def rz_close(self) -> None:
-        if self._stop_pending:
-            self.log_error("The stop_value was not retrieved")
+        """Remove and return an item from the memory cell."""
+        while True:
+            await self._has_value.wait()
+            if self._value is redzed.UNDEF:
+                if self._shutdown:
+                    raise BufferShutDown("The buffer was shut down")
+                if not self._has_value.is_set():
+                    raise RuntimeError("BUG!: busy loop prevented")
+                continue
+            value, self._value = self._value, redzed.UNDEF
+            if not self._shutdown:
+                self._has_value.clear()
+            return value
 
 
 class OutputWorker(redzed.Block):
     """
-    Run a coroutine for each value from a buffer.
+    Run an awaitable for each value from a buffer.
     """
 
     def __init__(
             self, *args,
             buffer: str|redzed.Block,
-            coro_func: Callable[[t.Any], Awaitable[t.Any]],   # i.e. an async function
+            aw_func: Callable[[t.Any], Awaitable[t.Any]],   # e.g. an async function
             workers: int = 1,
             **kwargs) -> None:
         super().__init__(*args, **kwargs)
         if workers < 1:
             raise ValueError(f"{self}: At least one worker is required")
         self._buffer = buffer
-        self._corofunc = coro_func
+        self._aw_func = aw_func
         self._workers = workers
         self._worker_tasks: list[asyncio.Task[None]] = []
 
@@ -222,10 +251,9 @@ class OutputWorker(redzed.Block):
             try:
                 if redzed.get_debug_level() >= 1:
                     self.log_debug(
-                        "%s: Awaiting coroutine %s",
-                        wname, func_call_string(self._corofunc, (value,)))
-                await self._corofunc(value)
-                self.log_debug2("%s: coroutine done", wname)
+                        "%s: Awaiting %s", wname, func_call_string(self._aw_func, (value,)))
+                await self._aw_func(value)
+                self.log_debug2("%s: await done", wname)
             except Exception as err:
                 err.add_note(f"Processed value was: {value!r}")
                 raise
@@ -241,27 +269,31 @@ class OutputWorker(redzed.Block):
                     self._worker(wname), auto_cancel=False, name=f"{self}: {wname}"))
 
     async def rz_astop(self) -> None:
+        worker_tasks = [worker for worker in self._worker_tasks if not worker.done()]
+        if not worker_tasks:
+            return
         try:
-            await asyncio.wait(self._worker_tasks)
+            await asyncio.wait(worker_tasks)
         except asyncio.CancelledError:
             # stop_timeout from the circuit runner
-            for worker in self._worker_tasks:
+            for worker in worker_tasks:
                 if not worker.done():
                     worker.cancel()
             await asyncio.sleep(0)
-            if (running := sum(1 for worker in self._worker_tasks if not worker.done())) > 0:
+            if (running := sum(1 for worker in worker_tasks if not worker.done())) > 0:
                 self.log_warning("%d worker(s) did not stop", running)
             raise
 
+
 class OutputController(redzed.Block):
     """
-    Run a coroutine for the latest value from a buffer.
+    Run an awaitable for the latest value from a buffer.
     """
 
     def __init__(
             self, *args,
             buffer: str|redzed.Block,
-            coro_func: Callable[[t.Any], Awaitable[t.Any]],     # i.e. an async function
+            aw_func: Callable[[t.Any], Awaitable[t.Any]],     # e.g. an async function
             rest_time: float|str = 0.0,
             **kwargs) -> None:
         super().__init__(*args, **kwargs)
@@ -269,7 +301,7 @@ class OutputController(redzed.Block):
         if self._rest_time >= self.rz_stop_timeout:
             raise ValueError(f"{self}: rest_time must be shorter than the stop_timeout")
         self._buffer = buffer
-        self._corofunc = coro_func
+        self._aw_func = aw_func
         self._main_loop_task: asyncio.Task[None]|None = None
 
     def rz_pre_init(self) -> None:
@@ -284,7 +316,7 @@ class OutputController(redzed.Block):
 
     async def _run_with_rest_time(self, value: t.Any) -> None:
         try:
-            await self._corofunc(value)
+            await self._aw_func(value)
         except asyncio.CancelledError:
             self.log_debug2("Task cancelled")
             await self._rest_time_delay()
@@ -331,7 +363,7 @@ class OutputController(redzed.Block):
             if redzed.get_debug_level() >= 1:
                 self.log_debug(
                     "Creating task: %s%s",
-                    func_call_string(self._corofunc, (value,)),
+                    func_call_string(self._aw_func, (value,)),
                     " + rest time" if self._rest_time > 0.0 else "",
                     )
             task = asyncio.create_task(self._run_with_rest_time(value))

redzed/blocklib/repeat.py

@@ -13,7 +13,7 @@ import asyncio
 import typing as t
 
 import redzed
-from redzed.utils import MsgSync, time_period
+from redzed.utils import time_period
 
 
 class Repeat(redzed.Block):
@@ -27,20 +27,27 @@ class Repeat(redzed.Block):
             **kwargs
             ) -> None:
         self._dest = dest
-        self._interval = time_period(interval)
+        self._default_interval = time_period(interval)
         if count is not None and count < 0:
             # count = 0 (no repeating) is accepted
             raise ValueError("argument 'count' must not be negative")
-        self._count = count
-        self._sync: MsgSync[tuple[str, redzed.EventData]] = MsgSync()
-        self._warning_logged = False
+        self._default_count = count
+        self._got_event = False
+        self._new_event = asyncio.Event()
+        # current event
+        self._etype: str
+        self._edata: redzed.EventData
+        self._interval: float
+        self._count: int|None
         super().__init__(*args, **kwargs)
 
     def rz_pre_init(self) -> None:
         """Resolve destination block name."""
-        if not isinstance(dest := self.circuit.resolve_name(self._dest), redzed.Block):
-            raise TypeError(
-                f"{self}: {dest} is not a Block, but a Formula; cannot send events to it.")
+        dest = self.circuit.resolve_name(self._dest)
+        if isinstance(dest, redzed.Formula):
+            raise TypeError(f"{self}: {dest} is a Formula; cannot send events to it.")
+        if isinstance(dest, type(self)):
+            raise TypeError(f"{self}: {dest} is another Repeat block; this is not allowed")
         self._dest = dest
         self.circuit.create_service(self._repeater(), name=f"Event repeating task at {self}")
 
@@ -52,21 +59,30 @@ class Repeat(redzed.Block):
         repeat = 0      # prevent pylint warning
         while True:
             try:
-                etype, edata = await self._sync.recv(
-                    timeout=self._interval if repeating else None)
-                repeat = 0
+                async with asyncio.timeout(self._interval if repeating else None):
+                    await self._new_event.wait()
             except asyncio.TimeoutError:
+                pass
+            # getting a timeout does not necessarily mean the event was not set
+            if self._new_event.is_set():
+                self._new_event.clear()
+                repeat = 0
+            else:
                 repeat += 1
 
             if repeat > 0:  # skip the original event
                 self._set_output(repeat)
                 assert isinstance(self._dest, redzed.Block)    # @mypy: name resolved
-                self._dest.event(etype, **(edata | {'repeat': repeat}))
+                self._dest.event(self._etype, **(self._edata | {'repeat': repeat}))
             repeating = self._count is None or repeat < self._count
 
     def _default_event_handler(self, etype: str, edata: redzed.EventData) -> None:
         # send the original event synchronously
         self._set_output(0)
         assert isinstance(self._dest, redzed.Block)    # mypy: name is resolved
+        self._etype = etype
+        self._edata = edata
+        self._interval = edata.pop('repeat_interval', self._default_interval)
+        self._count = edata.pop('repeat_count', self._default_count)
         self._dest.event(etype, **(edata | {'repeat': 0}))
-        self._sync.send((etype, edata))
+        self._new_event.set()

redzed/blocklib/timedate.py

@@ -1,9 +1,9 @@
 """
 Periodic events at fixed time/date.
-
 - - - - - -
-Docs: https://edzed.readthedocs.io/en/latest/
-Home: https://github.com/xitop/edzed/
+Part of the redzed package.
+Docs: https://redzed.readthedocs.io/en/latest/
+Home: https://github.com/xitop/redzed/
 """
 
 from __future__ import annotations

redzed/blocklib/timeinterval.py

@@ -13,6 +13,10 @@ Intervals use those objects as endpoints:
     - DateTimeInterval defines non-recurring intervals.
 
 All intervals support the operation "value in interval".
+- - - - - -
+Part of the redzed package.
+Docs: https://redzed.readthedocs.io/en/latest/
+Home: https://github.com/xitop/redzed/
 """
 from __future__ import annotations
 

redzed/blocklib/timer.py

@@ -18,10 +18,9 @@ class Timer(FSM):
     A timer.
     """
 
-    ALL_STATES = ['off', 'on']
-    TIMED_STATES = [
-        ['on', float("inf"), 'off'],
-        ['off', float("inf"), 'on']]
+    STATES = [
+        ['off', float("inf"), 'on'],
+        ['on', float("inf"), 'off']]
     EVENTS = [
         ['start', ..., 'on'],
         ['stop', ..., 'off'],

redzed/blocklib/validator.py

@@ -0,0 +1,46 @@
+"""
+Data validator
+- - - - - -
+Part of the redzed package.
+Docs: https://redzed.readthedocs.io/en/latest/
+Home: https://github.com/xitop/redzed/
+"""
+from __future__ import annotations
+
+from collections.abc import Callable
+import typing as t
+
+class _Validate:
+    """
+    Add a value validator.
+
+    To be used as a redzed.Block mix-in class.
+    """
+
+    def __init__(
+            self, *args,
+            validator: Callable[[t.Any], t.Any]|None = None,
+            **kwargs) -> None:
+        self._validator = validator
+        super().__init__(*args, **kwargs)
+
+# mypy: disable-error-code=attr-defined
+# pylint: disable=no-member
+    def _validate(self, value: t.Any) -> t.Any:
+        """
+        Return the value processed by the validator.
+
+        Return the value unchanged if a validator was not configured.
+        The validator may raise to reject the value.
+        """
+        if self._validator is None:
+            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)
+            raise
+        if validated != value:
+            self.log_debug2("Validator has rewritten %r -> %r", value, validated)
+        return validated