redzed 25.12.30__py3-none-any.whl

redzed/blocklib/inputs.py

@@ -0,0 +1,210 @@
+"""
+A single memory cell blocks for general use.
+- - - - - -
+Part of the redzed package.
+Docs: https://edzed.readthedocs.io/en/latest/
+Home: https://github.com/xitop/edzed/
+"""
+from __future__ import annotations
+
+__all__ = ['Memory', 'MemoryExp', 'DataPoll']
+
+import asyncio
+from collections.abc import Callable, Sequence
+import time
+import typing as t
+
+import redzed
+from redzed.utils import is_multiple, time_period
+from .fsm import FSM
+
+
+class _Validate(redzed.Block):
+    """
+    Add a value validator.
+    """
+
+    def __init__(
+            self, *args,
+            validator: Callable[[t.Any], t.Any]|None = None,
+            **kwargs) -> None:
+        self._validator = validator
+        super().__init__(*args, **kwargs)
+
+    def _validate(self, value: t.Any) -> t.Any:
+        """
+        Return the value processed by the validator.
+
+        Return UNDEF if the validator rejected the value by raising
+        an exception. Return the value unchanged if a validator was
+        not configured.
+        """
+        if self._validator is None or value is redzed.UNDEF:
+            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)
+            return redzed.UNDEF
+        if validated != value:
+            self.log_debug2("Validator has rewritten %r -> %r", value, validated)
+        return validated
+
+
+class Memory(_Validate, redzed.Block):
+    """
+    Memory cell with optional value validation.
+
+    Memory is typically used as an input block.
+    """
+
+    def _store_value(self, value: t.Any) -> bool:
+        """
+        Validate and store a value.
+
+        Return True on success, False on validation error.
+        """
+        if (validated := self._validate(value)) is redzed.UNDEF:
+            return False
+        self._set_output(validated)
+        return True
+
+    def _event_store(self, edata: redzed.EventData) -> bool:
+        evalue = edata['evalue']
+        return self._store_value(evalue)
+
+    def rz_init(self, init_value: t.Any, /) -> None:
+        self._store_value(init_value)
+
+    def rz_export_state(self) -> t.Any:
+        return self.get()
+
+    def rz_restore_state(self, state: t.Any, /) -> None:
+        self._store_value(state)
+
+
+class MemoryExp(_Validate, FSM):
+    """
+    Memory cell with an expiration time.
+    """
+
+    ALL_STATES = ['expired', 'valid']
+    TIMED_STATES = [ ['valid', None, 'expired'], ]
+
+    def __init__(
+            self, *args,
+            duration: float|str|None,
+            expired: t.Any = None,
+            **kwargs) -> None:  # kwargs may contain a validator
+        super().__init__(*args, t_valid=duration, **kwargs)
+        self._expired = self._validate(expired)
+        if self._expired is redzed.UNDEF:
+            raise ValueError(
+                f"{self} The 'expired' argument {expired!r} was rejected by the validator")
+
+    def _event_store(self, edata: redzed.EventData) -> bool:
+        evalue = edata['evalue']
+        if (validated := self._validate(evalue)) is redzed.UNDEF:
+            return False
+        if validated == self._expired:
+            self._goto('expired')
+        else:
+            self.sdata['memory'] = validated
+            self._goto('valid')
+        return True
+
+    def rz_init(self, init_value: t.Any, /) -> None:
+        if (validated := self._validate(init_value)) is redzed.UNDEF:
+            return
+        if validated == self._expired:
+            super().rz_init('expired')
+        else:
+            self.sdata['memory'] = validated
+            super().rz_init('valid')
+
+    def enter_expired(self) -> None:
+        self.sdata.pop('memory', None)
+
+    def _set_output(self, output: t.Any) -> bool:
+        return super()._set_output(
+            self.sdata['memory'] if self.state == 'valid' else self._expired)
+
+
+class DataPoll(_Validate, redzed.Block):
+    """
+    A source of sampled or computed values.
+    """
+
+    def __init__(
+        self, *args,
+        func: Callable[[], t.Any],
+        interval: float|str,
+        retry_interval: None|float|str|Sequence[float|str] = None,
+        abort_after_failures: int = 0,
+        **kwargs) -> None:
+        self._func = func
+        self._interval = time_period(interval)
+        if retry_interval is None:
+            self._r_interval_min = self._r_interval_max = self._interval
+        elif is_multiple(retry_interval):
+            assert isinstance(retry_interval, Sequence)     # @mypy
+            if (ri_len := len(retry_interval)) != 2:
+                raise ValueError(
+                    "Exponential backoff expects exactly two values [T_min, T_max], "
+                    + f"but got {ri_len}")
+            self._r_interval_min = time_period(retry_interval[0])
+            self._r_interval_max = time_period(retry_interval[1])
+            if self._r_interval_max < self._r_interval_min * 2:
+                raise ValueError("Exponential backoff requires T_max >= 2*T_min")
+        else:
+            self._r_interval_min = self._r_interval_max = time_period(retry_interval)
+        if any (t <= 0.0 for t in [self._interval, self._r_interval_min, self._r_interval_max]):
+            raise ValueError(f"{self} Time intervals must be positive")
+        self._abort_after_failures = abort_after_failures
+        super().__init__(*args, **kwargs)
+
+    def rz_pre_init(self) -> None:
+        self.circuit.create_service(
+            self._poller(), name=f"Data polling task at {self}", immediate_start=True)
+
+    async def _poller(self) -> t.NoReturn:
+        """Data polling task: repeatedly get a value."""
+        await self.circuit.reached_state(redzed.CircuitState.INIT_BLOCKS)
+        failures = 0
+        while True:
+            value = self._func()
+            if asyncio.iscoroutine(value):
+                start_ts = time.monotonic()
+                value = await value
+                duration = time.monotonic() - start_ts
+            else:
+                duration = 0
+            if (value := self._validate(value)) is redzed.UNDEF:
+                failures += 1
+                self.log_debug1("Data acquisition failure(s): %d", failures)
+                if 0 < self._abort_after_failures <= failures:
+                    self.circuit.abort(
+                        RuntimeError(f"{self}: No data in {failures} polling cycle(s)"))
+                if failures == 1:
+                    interval = self._r_interval_min
+                elif interval < self._r_interval_max:
+                    interval = min(2*interval, self._r_interval_max)
+            else:
+                failures = 0
+                self._set_output(value)
+                interval = self._interval
+            if duration > 0:
+                interval = max(interval - duration, 0.0)
+            await asyncio.sleep(interval)
+        assert False, "Not reached"
+
+    def rz_init(self, init_value: t.Any, /) -> None:
+        self._set_output(init_value)
+
+    def rz_export_state(self) -> t.Any:
+        return self.get()
+
+    def rz_restore_state(self, state: t.Any, /) -> None:
+        if (value := self._validate(state)) is not redzed.UNDEF:
+            self._set_output(value)

redzed/blocklib/outputs.py

@@ -0,0 +1,361 @@
+"""
+Output blocks.
+- - - - - -
+Docs: https://edzed.readthedocs.io/en/latest/
+Home: https://github.com/xitop/edzed/
+"""
+from __future__ import annotations
+
+__all__ = ['MemoryBuffer', 'OutputFunc', 'OutputController', 'OutputWorker', 'QueueBuffer']
+
+import asyncio
+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
+
+
+class OutputFunc(redzed.Block):
+    """
+    Run a function when a value arrives.
+    """
+
+    def __init__(
+            self, *args,
+            func: Callable[..., t.Any],
+            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._func = func
+        self._parameters: list[tuple[str, bool]] = []    # item: (name, is_required)
+        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']
+        if redzed.get_debug_level() >= 1:
+            self.log_debug("Running %s", func_call_string(self._func, (arg,)))
+        try:
+            result = self._func(arg)
+        except Exception as err:
+            func_args = func_call_string(self._func, (arg,))
+            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)
+            raise
+        self.log_debug2("output function returned: %r", result)
+        return result
+
+    def rz_stop(self) -> None:
+        if self._stop_value is not redzed.UNDEF:
+            self._event_put({'evalue': self._stop_value})
+
+
+class _Buffer(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
+        if triggered_by is not redzed.UNDEF:
+            @redzed.triggered
+            def trigger(value=triggered_by) -> None:
+                self.event('put', value)
+
+    def rz_get_size(self) -> int:
+        raise NotImplementedError
+
+    async def rz_buffer_get(self) -> t.Any:
+        raise NotImplementedError
+
+
+class QueueBuffer(_Buffer):
+    """
+    FIFO buffer for output values.
+    """
+
+    def __init__(
+            self, *args,
+            maxsize: int = 0,
+            priority_queue: bool = False,
+            **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+        queue_type = asyncio.PriorityQueue if priority_queue else asyncio.Queue
+        self._queue: asyncio.Queue[t.Any] = queue_type(maxsize)
+        # 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_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)
+
+    async def rz_buffer_get(self) -> t.Any:
+        """
+        Remove and return the next value from the queue.
+        Wait for a value if the queue is empty.
+
+        After the shutdown drain the queue
+        and then raise BufferShutDown to each caller.
+        """
+        if self.circuit.after_shutdown() and self._queue.qsize() == 0:
+            raise BufferShutDown("The buffer was shut down")
+        self._waiters += 1
+        try:
+            value = await self._queue.get()
+        finally:
+            self._waiters -= 1
+        if value is redzed.UNDEF:
+            # unblocked in rz_stop
+            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):
+    """
+    Single memory cell buffer.
+    """
+
+    def __init__(self, *args, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+        self._cell: MsgSync[t.Any] = MsgSync()
+        self._stop_pending = False
+
+    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
+        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_stop(self) -> None:
+        """Shut down"""
+        self._cell.shutdown()
+        self._stop_pending = self._stop_value is not redzed.UNDEF
+
+    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")
+
+
+class OutputWorker(redzed.Block):
+    """
+    Run a coroutine 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
+            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._workers = workers
+        self._worker_tasks: list[asyncio.Task[None]] = []
+
+    def rz_pre_init(self) -> None:
+        self._buffer = self.circuit.resolve_name(self._buffer)  # type: ignore[assignment]
+        if not isinstance(self._buffer, _Buffer):
+            raise TypeError(
+                f"Check the buffer parameter; {self._buffer} is not a compatible block")
+
+    async def _worker(self, wname: str) -> None:
+        getter = self._buffer.rz_buffer_get     # type: ignore[union-attr]
+        while True:
+            try:
+                value = await getter()
+            except BufferShutDown:
+                return
+            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)
+            except Exception as err:
+                err.add_note(f"Processed value was: {value!r}")
+                raise
+
+    def rz_start(self) -> None:
+        workers = self._workers
+        for n in range(workers):
+            wname = "worker"
+            if workers > 1:
+                wname += f"={n+1}/{workers}"
+            self._worker_tasks.append(
+                self.circuit.create_service(
+                    self._worker(wname), auto_cancel=False, name=f"{self}: {wname}"))
+
+    async def rz_astop(self) -> None:
+        try:
+            await asyncio.wait(self._worker_tasks)
+        except asyncio.CancelledError:
+            # stop_timeout from the circuit runner
+            for worker in self._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:
+                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.
+    """
+
+    def __init__(
+            self, *args,
+            buffer: str|redzed.Block,
+            coro_func: Callable[[t.Any], Awaitable[t.Any]],     # i.e. an async function
+            rest_time: float|str = 0.0,
+            **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+        self._rest_time = time_period(rest_time, zero_ok=True)
+        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._main_loop_task: asyncio.Task[None]|None = None
+
+    def rz_pre_init(self) -> None:
+        self._buffer = self.circuit.resolve_name(self._buffer)  # type: ignore[assignment]
+        if not isinstance(self._buffer, _Buffer):
+            raise TypeError(
+                f"Check the buffer parameter; {self._buffer} is not a compatible block")
+
+    async def _rest_time_delay(self) -> None:
+        if self._rest_time > 0:
+            await cancel_shield(asyncio.sleep(self._rest_time))
+
+    async def _run_with_rest_time(self, value: t.Any) -> None:
+        try:
+            await self._corofunc(value)
+        except asyncio.CancelledError:
+            self.log_debug2("Task cancelled")
+            await self._rest_time_delay()
+            raise
+        except Exception as err:
+            err.add_note(f"Processed value was: {value!r}")
+            # this task is awaited only when a new task waits for its start
+            self.circuit.abort(err)
+            await self._rest_time_delay()
+            raise
+        await self._rest_time_delay()
+
+    async def _main_loop(self) -> None:
+        """
+        For each value from the buffer cancel the old task (if any)
+        and create a task. Exit after buffer's shutdown.
+        """
+        buffer = self._buffer
+        assert isinstance(buffer, _Buffer)  # @mypy
+        shutdown = False
+        task = None
+        while True:
+            try:
+                value = await buffer.rz_buffer_get()
+            except BufferShutDown:
+                shutdown = True
+            if task is not None:
+                if task.done():
+                    task.result()   # will re-raise task exception if any
+                else:
+                    if not shutdown:
+                        task.cancel()
+                    try:
+                        await task
+                    except asyncio.CancelledError:
+                        if asyncio.current_task().cancelling() > 0: # type: ignore[union-attr]
+                            raise
+                task = None
+            if shutdown:
+                return
+            if buffer.rz_get_size():
+                # a new value has arrived while we were awaiting the task
+                continue
+            if redzed.get_debug_level() >= 1:
+                self.log_debug(
+                    "Creating task: %s%s",
+                    func_call_string(self._corofunc, (value,)),
+                    " + rest time" if self._rest_time > 0.0 else "",
+                    )
+            task = asyncio.create_task(self._run_with_rest_time(value))
+
+    def rz_start(self) -> None:
+        self._main_loop_task = self.circuit.create_service(
+            self._main_loop(), auto_cancel=False, name=f"{self}: main loop")
+
+    async def rz_astop(self) -> None:
+        task = self._main_loop_task
+        if task is None or task.done():
+            return
+        try:
+            await task
+        except asyncio.CancelledError:
+            # stop_timeout from the circuit runner
+            task.cancel()
+            await asyncio.sleep(0)
+            if not task.done():
+                try:
+                    async with asyncio.timeout(self._rest_time):
+                        await task
+                except TimeoutError:
+                    pass
+            if not task.done():
+                self.log_warning("The main task did not stop")
+            raise

redzed/blocklib/repeat.py

@@ -0,0 +1,72 @@
+"""
+An event repeater.
+- - - - - -
+Part of the redzed package.
+Docs: https://redzed.readthedocs.io/en/latest/
+Home: https://github.com/xitop/redzed/
+"""
+from __future__ import annotations
+
+__all__ = ['Repeat']
+
+import asyncio
+import typing as t
+
+import redzed
+from redzed.utils import MsgSync, time_period
+
+
+class Repeat(redzed.Block):
+    """
+    Periodically repeat the last received event.
+    """
+
+    def __init__(
+            self, *args,
+            dest: str|redzed.Block, interval: float|str, count: int|None = None,
+            **kwargs
+            ) -> None:
+        self._dest = dest
+        self._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
+        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.")
+        self._dest = dest
+        self.circuit.create_service(self._repeater(), name=f"Event repeating task at {self}")
+
+    def rz_init_default(self) -> None:
+        self._set_output(0)
+
+    async def _repeater(self) -> t.NoReturn:
+        repeating = False
+        repeat = 0      # prevent pylint warning
+        while True:
+            try:
+                etype, edata = await self._sync.recv(
+                    timeout=self._interval if repeating else None)
+                repeat = 0
+            except asyncio.TimeoutError:
+                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}))
+            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._dest.event(etype, **(edata | {'repeat': 0}))
+        self._sync.send((etype, edata))