haiway 0.10.15__py3-none-any.whl → 0.10.17__py3-none-any.whl

haiway/helpers/asynchrony.py

@@ -0,0 +1,225 @@
+from asyncio import AbstractEventLoop, get_running_loop, iscoroutinefunction
+from collections.abc import Callable, Coroutine
+from concurrent.futures import Executor
+from contextvars import Context, copy_context
+from functools import partial
+from typing import Any, cast, overload
+
+from haiway.types.missing import MISSING, Missing
+
+__all__ = [
+    "asynchronous",
+    "wrap_async",
+]
+
+
+def wrap_async[**Args, Result](
+    function: Callable[Args, Coroutine[None, None, Result]] | Callable[Args, Result],
+    /,
+) -> Callable[Args, Coroutine[None, None, Result]]:
+    if iscoroutinefunction(function):
+        return function
+
+    else:
+
+        async def async_function(*args: Args.args, **kwargs: Args.kwargs) -> Result:
+            return cast(Callable[Args, Result], function)(*args, **kwargs)
+
+        _mimic_async(function, within=async_function)
+        return async_function
+
+
+@overload
+def asynchronous[**Args, Result]() -> Callable[
+    [Callable[Args, Result]],
+    Callable[Args, Coroutine[None, None, Result]],
+]: ...
+
+
+@overload
+def asynchronous[**Args, Result](
+    *,
+    loop: AbstractEventLoop | None = None,
+    executor: Executor,
+) -> Callable[
+    [Callable[Args, Result]],
+    Callable[Args, Coroutine[None, None, Result]],
+]: ...
+
+
+@overload
+def asynchronous[**Args, Result](
+    function: Callable[Args, Result],
+    /,
+) -> Callable[Args, Coroutine[None, None, Result]]: ...
+
+
+def asynchronous[**Args, Result](
+    function: Callable[Args, Result] | None = None,
+    /,
+    loop: AbstractEventLoop | None = None,
+    executor: Executor | Missing = MISSING,
+) -> (
+    Callable[
+        [Callable[Args, Result]],
+        Callable[Args, Coroutine[None, None, Result]],
+    ]
+    | Callable[Args, Coroutine[None, None, Result]]
+):
+    """\
+    Wrapper for a sync function to convert it to an async function. \
+    When specified an executor, it can be used to wrap long running or blocking synchronous \
+    operations within coroutines system.
+
+    Parameters
+    ----------
+    function: Callable[Args, Result]
+        function to be wrapped as running in loop executor.
+    loop: AbstractEventLoop | None
+        loop used to call the function. When None was provided the loop currently running while \
+        executing the function will be used. Default is None.
+    executor: Executor | Missing
+        executor used to run the function. When not provided (Missing) default loop executor\
+         will be used.
+
+    Returns
+    -------
+    Callable[_Args, _Result]
+        function wrapped to async using loop executor.
+    """
+
+    def wrap(
+        wrapped: Callable[Args, Result],
+    ) -> Callable[Args, Coroutine[None, None, Result]]:
+        assert not iscoroutinefunction(wrapped), "Cannot wrap async function in executor"  # nosec: B101
+
+        return _ExecutorWrapper(
+            wrapped,
+            loop=loop,
+            executor=cast(Executor | None, None if executor is MISSING else executor),
+        )
+
+    if function := function:
+        return wrap(wrapped=function)
+
+    else:
+        return wrap
+
+
+class _ExecutorWrapper[**Args, Result]:
+    def __init__(
+        self,
+        function: Callable[Args, Result],
+        /,
+        loop: AbstractEventLoop | None,
+        executor: Executor | None,
+    ) -> None:
+        self._function: Callable[Args, Result] = function
+        self._loop: AbstractEventLoop | None = loop
+        self._executor: Executor | None = executor
+
+        # mimic function attributes if able
+        _mimic_async(function, within=self)
+
+    async def __call__(
+        self,
+        *args: Args.args,
+        **kwargs: Args.kwargs,
+    ) -> Result:
+        context: Context = copy_context()
+        return await (self._loop or get_running_loop()).run_in_executor(
+            self._executor,
+            context.run,
+            partial(self._function, *args, **kwargs),
+        )
+
+    def __get__(
+        self,
+        instance: object,
+        owner: type | None = None,
+        /,
+    ) -> Callable[Args, Coroutine[None, None, Result]]:
+        if owner is None:
+            return self
+
+        else:
+            return _mimic_async(
+                self._function,
+                within=partial(
+                    self.__method_call__,
+                    instance,
+                ),
+            )
+
+    async def __method_call__(
+        self,
+        __method_self: object,
+        *args: Args.args,
+        **kwargs: Args.kwargs,
+    ) -> Result:
+        return await (self._loop or get_running_loop()).run_in_executor(
+            self._executor,
+            partial(self._function, __method_self, *args, **kwargs),
+        )
+
+
+def _mimic_async[**Args, Result](
+    function: Callable[Args, Result],
+    /,
+    within: Callable[..., Coroutine[None, None, Result]],
+) -> Callable[Args, Coroutine[None, None, Result]]:
+    try:
+        annotations: Any = getattr(  # noqa: B009
+            function,
+            "__annotations__",
+        )
+        setattr(  # noqa: B010
+            within,
+            "__annotations__",
+            {
+                **annotations,
+                "return": Coroutine[None, None, annotations.get("return", Any)],
+            },
+        )
+
+    except AttributeError:
+        pass
+
+    for attribute in (
+        "__module__",
+        "__name__",
+        "__qualname__",
+        "__doc__",
+        "__type_params__",
+        "__defaults__",
+        "__kwdefaults__",
+        "__globals__",
+    ):
+        try:
+            setattr(
+                within,
+                attribute,
+                getattr(
+                    function,
+                    attribute,
+                ),
+            )
+
+        except AttributeError:
+            pass
+    try:
+        within.__dict__.update(function.__dict__)
+
+    except AttributeError:
+        pass
+
+    setattr(  # noqa: B010 - mimic functools.wraps behavior for correct signature checks
+        within,
+        "__wrapped__",
+        function,
+    )
+
+    return cast(
+        Callable[Args, Coroutine[None, None, Result]],
+        within,
+    )

haiway/helpers/caching.py

@@ -0,0 +1,326 @@
+from asyncio import AbstractEventLoop, Task, get_running_loop, iscoroutinefunction, shield
+from collections import OrderedDict
+from collections.abc import Callable, Coroutine, Hashable
+from functools import _make_key, partial  # pyright: ignore[reportPrivateUsage]
+from time import monotonic
+from typing import NamedTuple, cast, overload
+from weakref import ref
+
+from haiway.utils.mimic import mimic_function
+
+__all__ = [
+    "cache",
+]
+
+
+@overload
+def cache[**Args, Result](
+    function: Callable[Args, Result],
+    /,
+) -> Callable[Args, Result]: ...
+
+
+@overload
+def cache[**Args, Result](
+    *,
+    limit: int = 1,
+    expiration: float | None = None,
+) -> Callable[[Callable[Args, Result]], Callable[Args, Result]]: ...
+
+
+def cache[**Args, Result](
+    function: Callable[Args, Result] | None = None,
+    *,
+    limit: int = 1,
+    expiration: float | None = None,
+) -> Callable[[Callable[Args, Result]], Callable[Args, Result]] | Callable[Args, Result]:
+    """\
+    Simple lru function result cache with optional expire time. \
+    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, _Result]
+        function to wrap in cache, either sync or async
+    limit: int
+        limit of cache entries to keep, default is 1
+    expiration: float | None
+        entries expiration time in seconds, default is None (not expiring)
+
+    Returns
+    -------
+    Callable[[Callable[_Args, _Result]], Callable[_Args, _Result]] | Callable[_Args, _Result]
+        provided function wrapped in cache
+    """
+
+    def _wrap(function: Callable[Args, Result]) -> Callable[Args, Result]:
+        if iscoroutinefunction(function):
+            return cast(
+                Callable[Args, Result],
+                _AsyncCache(
+                    function,
+                    limit=limit,
+                    expiration=expiration,
+                ),
+            )
+
+        else:
+            return cast(
+                Callable[Args, Result],
+                _SyncCache(
+                    function,
+                    limit=limit,
+                    expiration=expiration,
+                ),
+            )
+
+    if function := function:
+        return _wrap(function)
+
+    else:
+        return _wrap
+
+
+class _CacheEntry[Entry](NamedTuple):
+    value: Entry
+    expire: float | None
+
+
+class _SyncCache[**Args, Result]:
+    def __init__(
+        self,
+        function: Callable[Args, Result],
+        /,
+        limit: int,
+        expiration: float | None,
+    ) -> None:
+        self._function: Callable[Args, Result] = function
+        self._cached: OrderedDict[Hashable, _CacheEntry[Result]] = OrderedDict()
+        self._limit: int = limit
+        if expiration := expiration:
+
+            def next_expire_time() -> float | None:
+                return monotonic() + expiration
+
+        else:
+
+            def next_expire_time() -> float | None:
+                return None
+
+        self._next_expire_time: Callable[[], float | None] = next_expire_time
+
+        # mimic function attributes if able
+        mimic_function(function, within=self)
+
+    def __get__(
+        self,
+        instance: object | None,
+        owner: type | None = None,
+        /,
+    ) -> Callable[Args, Result]:
+        if owner is None or instance is None:
+            return self
+
+        else:
+            return mimic_function(
+                self._function,
+                within=partial(
+                    self.__method_call__,
+                    instance,
+                ),
+            )
+
+    def __call__(
+        self,
+        *args: Args.args,
+        **kwargs: Args.kwargs,
+    ) -> Result:
+        key: Hashable = _make_key(
+            args=args,
+            kwds=kwargs,
+            typed=True,
+        )
+
+        match self._cached.get(key):
+            case None:
+                pass
+
+            case entry:
+                if (expire := entry[1]) and expire < monotonic():
+                    # if still running let it complete if able
+                    del self._cached[key]  # continue the same way as if empty
+
+                else:
+                    self._cached.move_to_end(key)
+                    return entry[0]
+
+        result: Result = self._function(*args, **kwargs)
+        self._cached[key] = _CacheEntry(
+            value=result,
+            expire=self._next_expire_time(),
+        )
+
+        if len(self._cached) > self._limit:
+            # if still running let it complete if able
+            self._cached.popitem(last=False)
+
+        return result
+
+    def __method_call__(
+        self,
+        __method_self: object,
+        *args: Args.args,
+        **kwargs: Args.kwargs,
+    ) -> Result:
+        key: Hashable = _make_key(
+            args=(ref(__method_self), *args),
+            kwds=kwargs,
+            typed=True,
+        )
+
+        match self._cached.get(key):
+            case None:
+                pass
+
+            case entry:
+                if (expire := entry[1]) and expire < monotonic():
+                    # if still running let it complete if able
+                    del self._cached[key]  # continue the same way as if empty
+
+                else:
+                    self._cached.move_to_end(key)
+                    return entry[0]
+
+        result: Result = self._function(__method_self, *args, **kwargs)  # pyright: ignore[reportUnknownVariableType, reportCallIssue]
+        self._cached[key] = _CacheEntry(
+            value=result,  # pyright: ignore[reportUnknownArgumentType]
+            expire=self._next_expire_time(),
+        )
+        if len(self._cached) > self._limit:
+            # if still running let it complete if able
+            self._cached.popitem(last=False)
+
+        return result  # pyright: ignore[reportUnknownArgumentType, reportUnknownVariableType]
+
+
+class _AsyncCache[**Args, Result]:
+    def __init__(
+        self,
+        function: Callable[Args, Coroutine[None, None, Result]],
+        /,
+        limit: int,
+        expiration: float | None,
+    ) -> None:
+        self._function: Callable[Args, Coroutine[None, None, Result]] = function
+        self._cached: OrderedDict[Hashable, _CacheEntry[Task[Result]]] = OrderedDict()
+        self._limit: int = limit
+        if expiration := expiration:
+
+            def next_expire_time() -> float | None:
+                return monotonic() + expiration
+
+        else:
+
+            def next_expire_time() -> float | None:
+                return None
+
+        self._next_expire_time: Callable[[], float | None] = next_expire_time
+
+        # mimic function attributes if able
+        mimic_function(function, within=self)
+
+    def __get__(
+        self,
+        instance: object | None,
+        owner: type | None = None,
+        /,
+    ) -> Callable[Args, Coroutine[None, None, Result]]:
+        if owner is None or instance is None:
+            return self
+
+        else:
+            return mimic_function(
+                self._function,
+                within=partial(
+                    self.__method_call__,
+                    instance,
+                ),
+            )
+
+    async def __call__(
+        self,
+        *args: Args.args,
+        **kwargs: Args.kwargs,
+    ) -> Result:
+        loop: AbstractEventLoop = get_running_loop()
+        key: Hashable = _make_key(
+            args=args,
+            kwds=kwargs,
+            typed=True,
+        )
+
+        match self._cached.get(key):
+            case None:
+                pass
+
+            case entry:
+                if (expire := entry[1]) and expire < monotonic():
+                    # if still running let it complete if able
+                    del self._cached[key]  # continue the same way as if empty
+
+                else:
+                    self._cached.move_to_end(key)
+                    return await shield(entry[0])
+
+        task: Task[Result] = loop.create_task(self._function(*args, **kwargs))  # pyright: ignore[reportCallIssue]
+        self._cached[key] = _CacheEntry(
+            value=task,
+            expire=self._next_expire_time(),
+        )
+        if len(self._cached) > self._limit:
+            # if still running let it complete if able
+            self._cached.popitem(last=False)
+
+        return await shield(task)
+
+    async def __method_call__(
+        self,
+        __method_self: object,
+        *args: Args.args,
+        **kwargs: Args.kwargs,
+    ) -> Result:
+        loop: AbstractEventLoop = get_running_loop()
+        key: Hashable = _make_key(
+            args=(ref(__method_self), *args),
+            kwds=kwargs,
+            typed=True,
+        )
+
+        match self._cached.get(key):
+            case None:
+                pass
+
+            case entry:
+                if (expire := entry[1]) and expire < monotonic():
+                    # if still running let it complete if able
+                    del self._cached[key]  # continue the same way as if empty
+
+                else:
+                    self._cached.move_to_end(key)
+                    return await shield(entry[0])
+
+        task: Task[Result] = loop.create_task(
+            self._function(__method_self, *args, **kwargs),  # pyright: ignore[reportCallIssue, reportUnknownArgumentType]
+        )
+        self._cached[key] = _CacheEntry(
+            value=task,
+            expire=self._next_expire_time(),
+        )
+
+        if len(self._cached) > self._limit:
+            # if still running let it complete if able
+            self._cached.popitem(last=False)
+
+        return await shield(task)