haiway 0.1.0__py3-none-any.whl

haiway/helpers/retry.py

@@ -0,0 +1,210 @@
+from asyncio import CancelledError, iscoroutinefunction, sleep
+from collections.abc import Callable, Coroutine
+from typing import cast, overload
+
+from haiway.context import ctx
+from haiway.utils import mimic_function
+
+__all__ = [
+    "auto_retry",
+]
+
+
+@overload
+def auto_retry[**Args, Result](
+    function: Callable[Args, Result],
+    /,
+) -> Callable[Args, Result]:
+    """\
+    Function wrapper retrying the wrapped function again on fail. \
+    Works for both sync and async functions. \
+    It is not allowed to be used on class methods. \
+    This wrapper is not thread safe.
+
+    Parameters
+    ----------
+    function: Callable[_Args_T, _Result_T]
+        function to wrap in auto retry, either sync or async.
+
+    Returns
+    -------
+    Callable[_Args_T, _Result_T]
+        provided function wrapped in auto retry with default configuration.
+    """
+
+
+@overload
+def auto_retry[**Args, Result](
+    *,
+    limit: int = 1,
+    delay: Callable[[int, Exception], float] | float | None = None,
+    catching: set[type[Exception]] | tuple[type[Exception], ...] | type[Exception] = Exception,
+) -> Callable[[Callable[Args, Result]], Callable[Args, Result]]:
+    """\
+    Function wrapper retrying the wrapped function again on fail. \
+    Works for both sync and async functions. \
+    It is not allowed to be used on class methods. \
+    This wrapper is not thread safe.
+
+    Parameters
+    ----------
+    limit: int
+        limit of retries, default is 1
+    delay: Callable[[int, Exception], float] | float | None
+        retry delay time in seconds, either concrete value or a function producing it, \
+        default is None (no delay)
+    catching: set[type[Exception]] | type[Exception] | None
+        Exception types that are triggering auto retry. Retry will trigger only when \
+        exceptions of matching types (including subclasses) will occur. CancelledError \
+        will be always propagated even if specified explicitly.
+        Default is Exception - all subclasses of Exception will be handled.
+
+    Returns
+    -------
+    Callable[[Callable[_Args_T, _Result_T]], Callable[_Args_T, _Result_T]]
+        function wrapper for adding auto retry
+    """
+
+
+def auto_retry[**Args, Result](
+    function: Callable[Args, Result] | None = None,
+    *,
+    limit: int = 1,
+    delay: Callable[[int, Exception], float] | float | None = None,
+    catching: set[type[Exception]] | tuple[type[Exception], ...] | type[Exception] = Exception,
+) -> Callable[[Callable[Args, Result]], Callable[Args, Result]] | Callable[Args, Result]:
+    """\
+    Function wrapper retrying the wrapped function again on fail. \
+    Works for both sync and async functions. \
+    It is not allowed to be used on class methods. \
+    This wrapper is not thread safe.
+
+    Parameters
+    ----------
+    function: Callable[_Args_T, _Result_T]
+        function to wrap in auto retry, either sync or async.
+    limit: int
+        limit of retries, default is 1
+    delay: Callable[[int, Exception], float] | float | None
+        retry delay time in seconds, either concrete value or a function producing it, \
+        default is None (no delay)
+    catching: set[type[Exception]] | type[Exception] | None
+        Exception types that are triggering auto retry. Retry will trigger only when \
+        exceptions of matching types (including subclasses) will occur. CancelledError \
+        will be always propagated even if specified explicitly.
+        Default is Exception - all subclasses of Exception will be handled.
+
+    Returns
+    -------
+    Callable[[Callable[_Args_T, _Result_T]], Callable[_Args_T, _Result_T]] | \
+    Callable[_Args_T, _Result_T]
+        function wrapper for adding auto retry or a wrapped function
+    """
+
+    def _wrap(
+        function: Callable[Args, Result],
+        /,
+    ) -> Callable[Args, Result]:
+        if iscoroutinefunction(function):
+            return cast(
+                Callable[Args, Result],
+                _wrap_async(
+                    function,
+                    limit=limit,
+                    delay=delay,
+                    catching=catching if isinstance(catching, set | tuple) else {catching},
+                ),
+            )
+        else:
+            assert delay is None, "Delay is not supported in sync wrapper"  # nosec: B101
+            return _wrap_sync(
+                function,
+                limit=limit,
+                catching=catching if isinstance(catching, set | tuple) else {catching},
+            )
+
+    if function := function:
+        return _wrap(function)
+    else:
+        return _wrap
+
+
+def _wrap_sync[**Args, Result](
+    function: Callable[Args, Result],
+    *,
+    limit: int,
+    catching: set[type[Exception]] | tuple[type[Exception], ...],
+) -> Callable[Args, Result]:
+    assert limit > 0, "Limit has to be greater than zero"  # nosec: B101
+
+    @mimic_function(function)
+    def wrapped(
+        *args: Args.args,
+        **kwargs: Args.kwargs,
+    ) -> Result:
+        attempt: int = 0
+        while True:
+            try:
+                return function(*args, **kwargs)
+            except CancelledError as exc:
+                raise exc
+
+            except Exception as exc:
+                if attempt < limit and any(isinstance(exc, exception) for exception in catching):
+                    attempt += 1
+                    ctx.log_error(
+                        "Attempting to retry %s which failed due to an error: %s",
+                        function.__name__,
+                        exc,
+                    )
+
+                else:
+                    raise exc
+
+    return wrapped
+
+
+def _wrap_async[**Args, Result](
+    function: Callable[Args, Coroutine[None, None, Result]],
+    *,
+    limit: int,
+    delay: Callable[[int, Exception], float] | float | None,
+    catching: set[type[Exception]] | tuple[type[Exception], ...],
+) -> Callable[Args, Coroutine[None, None, Result]]:
+    assert limit > 0, "Limit has to be greater than zero"  # nosec: B101
+
+    @mimic_function(function)
+    async def wrapped(
+        *args: Args.args,
+        **kwargs: Args.kwargs,
+    ) -> Result:
+        attempt: int = 0
+        while True:
+            try:
+                return await function(*args, **kwargs)
+            except CancelledError as exc:
+                raise exc
+
+            except Exception as exc:
+                if attempt < limit and any(isinstance(exc, exception) for exception in catching):
+                    attempt += 1
+                    ctx.log_error(
+                        "Attempting to retry %s which failed due to an error",
+                        function.__name__,
+                        exception=exc,
+                    )
+
+                    match delay:
+                        case None:
+                            continue
+
+                        case float(strict):
+                            await sleep(delay=strict)
+
+                        case make_delay:  # type: Callable[[], float]
+                            await sleep(delay=make_delay(attempt, exc))  # pyright: ignore[reportCallIssue, reportUnknownArgumentType]
+
+                else:
+                    raise exc
+
+    return wrapped

haiway/helpers/throttling.py

@@ -0,0 +1,133 @@
+from asyncio import (
+    Lock,
+    iscoroutinefunction,
+    sleep,
+)
+from collections import deque
+from collections.abc import Callable, Coroutine
+from datetime import timedelta
+from time import monotonic
+from typing import cast, overload
+
+from haiway.utils.mimic import mimic_function
+
+__all__ = [
+    "throttle",
+]
+
+
+@overload
+def throttle[**Args, Result](
+    function: Callable[Args, Coroutine[None, None, Result]],
+    /,
+) -> Callable[Args, Coroutine[None, None, Result]]: ...
+
+
+@overload
+def throttle[**Args, Result](
+    *,
+    limit: int = 1,
+    period: timedelta | float = 1,
+) -> Callable[
+    [Callable[Args, Coroutine[None, None, Result]]], Callable[Args, Coroutine[None, None, Result]]
+]: ...
+
+
+def throttle[**Args, Result](
+    function: Callable[Args, Coroutine[None, None, Result]] | None = None,
+    *,
+    limit: int = 1,
+    period: timedelta | float = 1,
+) -> (
+    Callable[
+        [Callable[Args, Coroutine[None, None, Result]]],
+        Callable[Args, Coroutine[None, None, Result]],
+    ]
+    | Callable[Args, Coroutine[None, None, Result]]
+):
+    """\
+    Throttle for function calls with custom limit and period time. \
+    Works only for async functions by waiting desired time before execution. \
+    It is not allowed to be used on class or instance methods. \
+    This wrapper is not thread safe.
+
+    Parameters
+    ----------
+    function: Callable[Args, Coroutine[None, None, Result]]
+        function to wrap in throttle
+    limit: int
+        limit of executions in given period, if no period was specified
+        it is number of concurrent executions instead, default is 1
+    period: timedelta | float | None
+        period time (in seconds by default) during which the limit resets, default is 1 second
+
+    Returns
+    -------
+    Callable[[Callable[Args, Coroutine[None, None, Result]]], Callable[Args, Coroutine[None, None, Result]]] \
+    | Callable[Args, Coroutine[None, None, Result]]
+        provided function wrapped in throttle
+    """  # noqa: E501
+
+    def _wrap(
+        function: Callable[Args, Coroutine[None, None, Result]],
+    ) -> Callable[Args, Coroutine[None, None, Result]]:
+        assert iscoroutinefunction(function)  # nosec: B101
+        return cast(
+            Callable[Args, Coroutine[None, None, Result]],
+            _AsyncThrottle(
+                function,
+                limit=limit,
+                period=period,
+            ),
+        )
+
+    if function := function:
+        return _wrap(function)
+
+    else:
+        return _wrap
+
+
+class _AsyncThrottle[**Args, Result]:
+    def __init__(
+        self,
+        function: Callable[Args, Coroutine[None, None, Result]],
+        /,
+        limit: int,
+        period: timedelta | float,
+    ) -> None:
+        self._function: Callable[Args, Coroutine[None, None, Result]] = function
+        self._entries: deque[float] = deque()
+        self._lock: Lock = Lock()
+        self._limit: int = limit
+        self._period: float
+        match period:
+            case timedelta() as delta:
+                self._period = delta.total_seconds()
+
+            case period_seconds:
+                self._period = period_seconds
+
+        # mimic function attributes if able
+        mimic_function(function, within=self)
+
+    async def __call__(
+        self,
+        *args: Args.args,
+        **kwargs: Args.kwargs,
+    ) -> Result:
+        async with self._lock:
+            time_now: float = monotonic()
+            while self._entries:  # cleanup old entries
+                if self._entries[0] + self._period <= time_now:
+                    self._entries.popleft()
+
+                else:
+                    break
+
+            if len(self._entries) >= self._limit:
+                await sleep(self._entries[0] - time_now)
+
+            self._entries.append(monotonic())
+
+        return await self._function(*args, **kwargs)

haiway/helpers/timeout.py

@@ -0,0 +1,112 @@
+from asyncio import AbstractEventLoop, Future, Task, TimerHandle, get_running_loop
+from collections.abc import Callable, Coroutine
+
+from haiway.utils.mimic import mimic_function
+
+__all__ = [
+    "with_timeout",
+]
+
+
+def with_timeout[**Args, Result](
+    timeout: float,
+    /,
+) -> Callable[
+    [Callable[Args, Coroutine[None, None, Result]]],
+    Callable[Args, Coroutine[None, None, Result]],
+]:
+    """\
+    Timeout wrapper for a function call. \
+    When the timeout time will pass before function returns function execution will be \
+    cancelled and TimeoutError exception will raise. Make sure that wrapped \
+    function handles cancellation properly.
+    This wrapper is not thread safe.
+
+    Parameters
+    ----------
+    timeout: float
+        timeout time in seconds
+
+    Returns
+    -------
+    Callable[[Callable[_Args, _Result]], Callable[_Args, _Result]] | Callable[_Args, _Result]
+        function wrapper adding timeout
+    """
+
+    def _wrap(
+        function: Callable[Args, Coroutine[None, None, Result]],
+    ) -> Callable[Args, Coroutine[None, None, Result]]:
+        return _AsyncTimeout(
+            function,
+            timeout=timeout,
+        )
+
+    return _wrap
+
+
+class _AsyncTimeout[**Args, Result]:
+    def __init__(
+        self,
+        function: Callable[Args, Coroutine[None, None, Result]],
+        /,
+        timeout: float,
+    ) -> None:
+        self._function: Callable[Args, Coroutine[None, None, Result]] = function
+        self._timeout: float = timeout
+
+        # mimic function attributes if able
+        mimic_function(function, within=self)
+
+    async def __call__(
+        self,
+        *args: Args.args,
+        **kwargs: Args.kwargs,
+    ) -> Result:
+        loop: AbstractEventLoop = get_running_loop()
+        future: Future[Result] = loop.create_future()
+        task: Task[Result] = loop.create_task(
+            self._function(
+                *args,
+                **kwargs,
+            ),
+        )
+
+        def on_timeout(
+            future: Future[Result],
+        ) -> None:
+            if future.done():
+                return  # ignore if already finished
+
+            # result future on its completion will ensure that task will complete
+            future.set_exception(TimeoutError())
+
+        timeout_handle: TimerHandle = loop.call_later(
+            self._timeout,
+            on_timeout,
+            future,
+        )
+
+        def on_completion(
+            task: Task[Result],
+        ) -> None:
+            timeout_handle.cancel()  # at this stage we no longer need timeout to trigger
+
+            if future.done():
+                return  # ignore if already finished
+
+            try:
+                future.set_result(task.result())
+
+            except Exception as exc:
+                future.set_exception(exc)
+
+        task.add_done_callback(on_completion)
+
+        def on_result(
+            future: Future[Result],
+        ) -> None:
+            task.cancel()  # when result future completes make sure that task also completes
+
+        future.add_done_callback(on_result)
+
+        return await future

haiway/state/__init__.py

@@ -0,0 +1,8 @@
+from haiway.state.attributes import AttributeAnnotation, attribute_annotations
+from haiway.state.structure import Structure
+
+__all__ = [
+    "attribute_annotations",
+    "AttributeAnnotation",
+    "Structure",
+]