redzed 25.12.30__py3-none-any.whl

redzed/initializers.py

@@ -0,0 +1,249 @@
+"""
+Block initializers.
+- - - - - -
+Part of the redzed package.
+# Docs: https://redzed.readthedocs.io/en/latest/
+# Project home: https://github.com/xitop/redzed/
+"""
+from __future__ import annotations
+
+__all__ = [
+    'AsyncInitializer', 'SyncInitializer',
+    'InitFunction', 'InitTask', 'InitValue', 'InitWait', 'RestoreState']
+
+import asyncio
+from collections.abc import Callable, Awaitable
+import time
+import typing as t
+
+from . import block
+from .undef import UNDEF, UndefType
+from .utils import check_async_func, time_period
+
+
+_LONG_TIMEOUT = 60      # threshold for a "long timeout" debug message
+
+
+class SyncInitializer:
+    """
+    Logic block initializers are used as initial=... arguments.
+
+    A block can have multiple initializers. They will be called
+    in given order until the first one succeeds.
+    """
+
+    def __init__(self) -> None:
+        # Keep track in order to prevent repeated application of the same initializer.
+        # It could happen when a block receives an event during initialization.
+        self._applied = False
+
+    @property
+    def type_name(self) -> str:
+        return type(self).__name__
+
+    def _get_init(self) -> t.Any:
+        """Return the initial value or UNDEF if not available."""
+        raise NotImplementedError()
+
+    def apply_to(self, blk: block.Block) -> None:
+        """
+        Apply this initializer to a logic block *blk*.
+
+        Log exceptions, but do not propagate them. An error condition
+        is when a block doesn't get proper initialization after using
+        ALL initializers.
+        """
+        if self._applied:
+            return
+        self._applied = True
+        try:
+            init_value = self._get_init()
+        except Exception as err:
+            blk.log_error(
+                "%s: could not get the initialization value: %r", self.type_name, err)
+            return
+        blk.log_debug2("%s: init value: %r", self.type_name, init_value)
+        if init_value is UNDEF:
+            return
+        try:
+            blk.rz_init(init_value)    # type: ignore[attr-defined]
+        except Exception as err:
+            blk.log_error(
+                "%s could not apply the initialization value: %r", self.type_name, err)
+            return
+
+
+class InitFunction(SyncInitializer):
+    """
+    Initialize with a calculated value.
+    """
+
+    def __init__(self, func: Callable[..., t.Any], *args: t.Any) -> None:
+        """
+        Usage: InitFunction(func, arg1, arg2, ...)
+        Use functools.partial to pass keyword arguments.
+        """
+        super().__init__()
+        if not callable(func):
+            raise TypeError(f"{self.type_name}: {func!r} is not a function")
+        self._func = func
+        self._args = args
+
+    def _get_init(self) -> t.Any:
+        return self._func(*self._args)
+
+
+class InitValue(SyncInitializer):
+    """
+    Initialize with a literal value.
+    """
+
+    def __init__(self, value: t.Any) -> None:
+        super().__init__()
+        if value is UNDEF:
+            raise ValueError("<UNDEF> is not a valid initialization value.")
+        self._value = value
+
+    def _get_init(self) -> t.Any:
+        return self._value
+
+
+_CHECKPOINTS = [None, 'event', 'interval']
+
+class RestoreState(SyncInitializer):
+    """Restore from saved state."""
+
+    def __init__(
+            self,
+            checkpoints: None|t.Literal['event', 'interval'] = None,
+            expiration: None|float|str = None
+            ) -> None:
+        super().__init__()
+        if not checkpoints in _CHECKPOINTS:
+            raise ValueError(
+                "Parameter checkpoints must be one of: "
+                + f"{', '.join(repr(ch) for ch in _CHECKPOINTS)}")
+        self.rz_checkpoints = checkpoints
+        self._expiration = time_period(expiration, passthrough=None)
+
+    def _get_init(self) -> t.Any:
+        pass
+
+    def _get_state(self, blk: block.Block) -> t.Any:
+        storage = blk.circuit.rz_persistent_dict
+        assert storage is not None
+        try:
+            state, timestamp = storage[blk.rz_key]
+        except KeyError:
+            blk.log_debug2("No saved state was found")
+            return UNDEF
+        except Exception as err:
+            blk.log_warning("State retrieval error: %r", err)
+            return UNDEF
+        if self._expiration is None:
+            return state
+        age = time.time() - timestamp
+        if age < 0:
+            blk.log_error(
+                "The timestamp of saved data is in the future, check the system time")
+        elif age > self._expiration:
+            blk.log_debug2("The saved state has expired")
+            return UNDEF
+        return state
+
+    def apply_to(self, blk: block.Block) -> None:
+        if self._applied:
+            return
+        self._applied = True
+        if not blk.rz_persistence:
+            return
+        try:
+            init_state = self._get_state(blk)
+        except Exception as err:
+            blk.log_error(
+                "%s could not get the initialization value: %r", self.type_name, err)
+            return
+        if init_state is UNDEF:
+            # a debug message was logged in _get_state
+            return
+        blk.log_debug2("%s: saved state: %r", self.type_name, init_state)
+        try:
+            blk.rz_restore_state(init_state)       # type: ignore[attr-defined]
+        except Exception as err:
+            blk.log_error(
+                "%s could not apply the initialization value: %r", self.type_name, err)
+            return
+
+
+class AsyncInitializer:
+    """
+    Asynchronous initializer.
+    """
+
+    def __init__(self, timeout: float|str):
+        self._applied = False
+        self._timeout = time_period(timeout, passthrough=None)
+
+    @property
+    def type_name(self) -> str:
+        return type(self).__name__
+
+    async def _async_get_init(self) -> t.Any:
+        """Async version of _get_init."""
+        raise NotImplementedError()
+
+    async def async_apply_to(self, blk: block.Block) -> None:
+        """Async version of apply(). Do not overwrite existing state."""
+        if self._applied:
+            return
+        self._applied = True
+        if self._timeout >= _LONG_TIMEOUT:
+            blk.log_debug2("%s has a long timeout of %.1f secs", self.type_name, self._timeout)
+        try:
+            init_value = await self._async_get_init()
+        except TimeoutError:
+            blk.log_debug1("%s timed out", self.type_name)
+            return
+        except Exception as err:
+            blk.log_error("Skipping failed %s. Error: %r", self.type_name, err)
+            return
+        blk.log_debug2("%s: init value: %r", self.type_name, init_value)
+        if init_value is UNDEF:
+            return
+        if not blk.is_undef():
+            blk.log_debug1(
+                "%s: not applying the init value, because the block "
+                + "has been initialized in the meantime", self.type_name)
+            return
+        blk.rz_init(init_value)    # type: ignore[attr-defined]
+
+
+class InitTask(AsyncInitializer):
+    """
+    Initialize with a value calculated by a coroutine.
+    """
+
+    def __init__(
+            self,
+            coro_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._args = args
+
+    async def _async_get_init(self) -> t.Any:
+        async with asyncio.timeout(self._timeout):
+            return await self._corofunc(*self._args)
+
+
+class InitWait(AsyncInitializer):
+    """
+    Passively wait for initialization by an event.
+    """
+
+    async def _async_get_init(self) -> UndefType:
+        return await asyncio.sleep(self._timeout, result=UNDEF)

redzed/signal_shutdown.py

@@ -0,0 +1,64 @@
+"""
+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/
+"""
+from __future__ import annotations
+
+__all__ = ['TerminatingSignal']
+
+import asyncio
+from collections.abc import Callable
+import logging
+import signal
+from types import FrameType
+import typing as t
+
+from . import circuit
+
+_logger = logging.getLogger(__package__)
+
+
+class TerminatingSignal:
+    """
+    A context manager gracefully stopping the runner after signal.
+    """
+
+    def __init__(self, signo: int|None) -> None:
+        self._signo = signo
+        if signo is None:
+            return
+        self._saved_handler: Callable[[int, FrameType|None], None]|int|None
+        self._signame = signal.strsignal(signo) or f"#{signo}"
+
+    def __enter__(self) -> None:
+        if self._signo is None:
+            return
+        self._saved_handler = signal.getsignal(self._signo)
+        if self._saved_handler is None:
+            _logger.warning(
+                "An incompatible handler for signal %s was found; "
+                + "Redzed will not catch this signal.",
+                self._signame
+                )
+        else:
+            signal.signal(self._signo, self._handler)
+
+    def __exit__(self, _exc_type, _exc_val, _exc_tb) -> t.Literal[False]:
+        if self._signo is not None and self._saved_handler is not None:
+            signal.signal(self._signo, self._saved_handler)
+        return False
+
+    def _handler(self, signo: int, frame: FrameType|None) -> None:
+        """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()
+        msg = f"Signal {self._signame!r} caught"
+        call_soon = asyncio.get_running_loop().call_soon_threadsafe
+        call_soon(_logger.warning, "%s", msg)
+        call_soon(circuit.get_circuit().shutdown)
+        if callable(self._saved_handler):
+            self._saved_handler(signo, frame)

redzed/undef.py

@@ -0,0 +1,38 @@
+"""
+The UNDEF singleton constant.
+- - - - - -
+Part of the redzed package.
+# Docs: https://redzed.readthedocs.io/en/latest/
+# Home: https://github.com/xitop/redzed/
+"""
+from __future__ import annotations
+
+__all__ = ['UNDEF', 'UndefType']
+
+import enum
+import typing as t
+
+
+class DefaultEnumType(enum.EnumType):
+    """Allow an UndefType() call without parameters."""
+    # pylint: disable=keyword-arg-before-vararg
+    def __call__(cls, value=None, *args, **kwargs):
+        return super().__call__(value, *args, **kwargs)
+
+
+# See PEP 484 - Support for singleton types in unions
+class UndefType(enum.Enum, metaclass=DefaultEnumType):
+    """Undefined output value"""
+    UNDEF = None
+
+    def __bool__(self) -> bool:
+        return False
+
+    def __repr__(self) -> str:
+        return '<UNDEF>'
+
+    __str__ = __repr__
+
+
+# Uninitialized circuit block's state value
+UNDEF: t.Final = UndefType.UNDEF

redzed/utils/__init__.py

@@ -0,0 +1,14 @@
+"""
+Docs: https://redzed.readthedocs.io/en/latest/
+Home: https://github.com/xitop/redzed/
+"""
+
+from . import async_utils
+from . import data_utils
+from . import time_utils
+
+from .async_utils import *
+from .data_utils import *
+from .time_utils import *
+
+__all__ = async_utils.__all__  + data_utils.__all__  + time_utils.__all__

redzed/utils/async_utils.py

@@ -0,0 +1,145 @@
+"""
+Asynchronous utilities.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable
+import typing as t
+
+__all__ = ['BufferShutDown',  'cancel_shield', 'MsgSync']
+
+try:
+    BufferShutDown = asyncio.QueueShutDown      # Python 3.13+
+except AttributeError:
+    class BufferShutDown(Exception):            # type: ignore[no-redef]
+        """asyncio.QueueShutDown substitute"""
+
+
+_T = t.TypeVar("_T")
+_MISSING = object()
+
+class MsgSync(t.Generic[_T]):
+    """
+    Task synchronization based on sending messages of type _T.
+
+    The count of unread message is always either zero or one,
+    because messages are not queued. A new message replaces
+    the previous unread one, if any.
+
+    An existing unread message is available immediately.
+    Otherwise the recipient must wait and will be awakened when
+    a new message arrives. Reading a message consumes it,
+    so each message can reach only one receiver.
+    """
+
+    def __init__(self) -> None:
+        self._msg: t.Any = _MISSING
+        self._shutdown = False
+        self._has_data = asyncio.Event()    # valid before shutdown
+        self._draining = False              # valid after shutdown
+
+    def shutdown(self) -> None:
+        """
+        Disallow sending immediately. Disallow receiving after the MsgSync gets empty.
+
+        Calls to .send() will raise BufferShutDown.
+
+        If a message was sent before shutdown and is waiting, it can be
+        normally received before the receiver shuts down too. After
+        the shutdown all blocked callers will be unblocked with BufferShutDown.
+        Calls to .recv() will raise BufferShutDown as well.
+        """
+        self._shutdown = True
+        self._draining = self._has_data.is_set()
+        if not self._draining:
+            # wakeup all waiters
+            self._has_data.set()
+
+    def is_shutdown(self) -> bool:
+        """Check if the buffer was shut down."""
+        return self._shutdown
+
+    def send(self, msg: _T) -> None:
+        """
+        Send a message to one receiver.
+
+        If the previously sent message hasn't been received yet,
+        the new message overwrites it.
+        """
+        if self._shutdown:
+            raise BufferShutDown("The buffer was shut down")
+        self._msg = msg
+        self._has_data.set()
+
+    def clear(self) -> None:
+        """Remove the waiting message."""
+        if self._shutdown:
+            self._draining = False
+        else:
+            self._has_data.clear()
+        self._msg = _MISSING
+
+    def has_data(self) -> bool:
+        """Return True only if there is a waiting message."""
+        return self._draining if self._shutdown else self._has_data.is_set()
+
+    async def _recv(self) -> _T:
+        """Receive (consume) a message."""
+        while not self._has_data.is_set():
+            await self._has_data.wait()
+        if not self._shutdown:
+            self._has_data.clear()
+        elif self._draining:
+            self._draining = False
+        else:
+            raise BufferShutDown("The buffer was shut down")
+        msg, self._msg = self._msg, _MISSING
+        return t.cast(_T, msg)
+
+    async def recv(self, timeout: float | None = None, default: t.Any = _MISSING) -> t.Any:
+        """
+        Receive a message with optional timeout.
+
+        If a message is not available, wait until it arrives.
+
+        If a timeout [seconds] is given, return the default value
+        if no message is received before the timeout period elapses.
+        Without a default, raise the TimeoutError.
+        """
+        if timeout is None:
+            return await self._recv()
+        try:
+            async with asyncio.timeout(timeout):
+                return await self._recv()
+        except TimeoutError:
+            if default is not _MISSING:
+                return default
+            raise
+
+
+async def cancel_shield(aw: Awaitable[_T]) -> _T:
+    """
+    Shield from cancellation while aw is awaited.
+
+    Any pending CancelledError is raised when aw is finished.
+    """
+    task = asyncio.ensure_future(aw)
+    cancel_exc = None
+    while True:
+        try:
+            retval = await asyncio.shield(task)
+        except asyncio.CancelledError as err:
+            if task.done():
+                raise
+            cancel_exc = err
+        else:
+            break
+    if cancel_exc is not None:
+        try:
+            raise cancel_exc
+        finally:
+            # break the reference loop
+            cancel_exc = None
+    return retval

redzed/utils/data_utils.py

@@ -0,0 +1,116 @@
+"""
+Small utilities.
+"""
+from __future__ import annotations
+
+__all__ = [
+    'check_async_coro', 'check_async_func', 'check_identifier', 'func_call_string',
+    'is_multiple', 'tasks_are_eager', 'to_tuple']
+
+import asyncio
+from collections.abc import Callable, Mapping, Sequence
+import inspect
+import itertools
+import logging
+import typing as t
+
+_logger = logging.getLogger(__package__)
+
+
+def check_identifier(name: t.Any, msg_prefix: str) -> None:
+    """Raise if *name* is not a valid identifier."""
+    if not isinstance(name, str):
+        raise TypeError(f"{msg_prefix} must be a string, got {name!r}")
+    if not name:
+        raise ValueError(f"{msg_prefix} cannot be an empty string")
+    if not name.isidentifier():
+        raise ValueError(f"{msg_prefix} must be a valid identifier, got '{name!r}'")
+
+
+def is_multiple(arg: t.Any) -> bool:
+    """
+    Check if *arg* specifies multiple ordered items.
+
+    The check is based on the type. The actual item count does not
+    matter and can be any value including zero or one.
+    A string or a byte-string is considered a single argument.
+    """
+    return not isinstance(arg, (str, bytes)) and isinstance(arg, Sequence)
+
+
+_T_item = t.TypeVar("_T_item")
+def to_tuple(args: _T_item|Sequence[_T_item]) -> tuple[_T_item, ...]:
+    """Transform *args* to a tuple of items."""
+
+    if isinstance(args, tuple):
+        return args
+    if is_multiple(args):
+        assert isinstance(args, Sequence)   # @mypy
+        return tuple(args)
+    return t.cast(tuple[_T_item], (args,))
+
+
+# must not touch *kwargs* # pylint: disable-next=dangerous-default-value
+def func_call_string(
+        func: Callable[..., t.Any]|None,
+        args: Sequence[t.Any],
+        kwargs: Mapping[str, t.Any] = {}
+        ) -> str:
+    """Convert args and kwargs to a printable string."""
+    arglist = '(' + ', '.join(itertools.chain(
+        (repr(a) for a in args),
+        (f"{k}={v!r}" for k, v in kwargs.items()))) + ')'
+    if func is None:
+        return arglist
+    return func.__name__ + arglist
+
+
+def tasks_are_eager() -> bool:
+    """
+    Detect if eager tasks are enabled.
+
+    Eager tasks (Python 3.12+) change the order of execution.
+    The changed order may violate assumptions made in the
+    code written before eager tasks were introduced.
+    """
+    if not hasattr(asyncio, "eager_task_factory"):
+        return False
+    flag = False
+    async def test_task() -> None:
+        nonlocal flag
+        flag = True
+    asyncio.create_task(test_task())
+    return flag
+
+
+def check_async_coro(arg: t.Any) -> None:
+    """
+    Check if arg is a coroutine object.
+
+    Raise a TypeError with a descriptive message if it isn't.
+    """
+    if inspect.iscoroutine(arg):
+        return
+    if inspect.iscoroutinefunction(arg):
+        received = f"an async function '{arg.__name__}'. Did you mean '{arg.__name__}()'?"
+    else:
+        received = repr(arg)
+    raise TypeError(f"Expected a coroutine, but got {received}")
+
+
+def check_async_func(arg: t.Any) -> None:
+    """
+    Check if *arg* is an async function.
+
+    Raise a TypeError with a descriptive message if it isn't.
+    """
+    if inspect.iscoroutinefunction(arg):
+        return
+    if inspect.iscoroutine(arg):
+        received = (f"a coroutine '{arg.__name__}()'. "
+            + f"Did you mean '{arg.__name__}' without parentheses?")
+    elif callable(arg):
+        received = f"a non-async function/callable '{arg.__name__}'"
+    else:
+        received = repr(arg)
+    raise TypeError(f"Expected an async function, but got {received}")