haiway 0.12.1__py3-none-any.whl → 0.13.0__py3-none-any.whl

haiway/context/state.py

@@ -91,11 +91,6 @@ class ScopeState:
 class StateContext:
     _context = ContextVar[ScopeState]("StateContext")
 
-    __slots__ = (
-        "_state",
-        "_token",
-    )
-
     @classmethod
     def current[StateType: State](
         cls,
@@ -122,6 +117,11 @@ class StateContext:
         except LookupError:  # create root scope when missing
             return cls(state=ScopeState(state))
 
+    __slots__ = (
+        "_state",
+        "_token",
+    )
+
     def __init__(
         self,
         state: ScopeState,

haiway/helpers/caching.py

@@ -1,11 +1,11 @@
-from asyncio import AbstractEventLoop, Task, get_running_loop, iscoroutinefunction, shield
+from asyncio import iscoroutinefunction
 from collections import OrderedDict
 from collections.abc import Callable, Coroutine, Hashable
-from functools import _make_key, partial  # pyright: ignore[reportPrivateUsage]
+from functools import _make_key  # pyright: ignore[reportPrivateUsage]
 from time import monotonic
-from typing import NamedTuple, cast, overload
-from weakref import ref
+from typing import NamedTuple, Protocol, cast, overload
 
+from haiway.context.access import ctx
 from haiway.utils.mimic import mimic_function
 
 __all__ = [
@@ -13,6 +13,29 @@ __all__ = [
 ]
 
 
+class CacheMakeKey[**Args, Key](Protocol):
+    def __call__(
+        self,
+        *args: Args.args,
+        **kwargs: Args.kwargs,
+    ) -> Key: ...
+
+
+class CacheRead[Key, Value](Protocol):
+    async def __call__(
+        self,
+        key: Key,
+    ) -> Value | None: ...
+
+
+class CacheWrite[Key, Value](Protocol):
+    async def __call__(
+        self,
+        key: Key,
+        value: Value,
+    ) -> None: ...
+
+
 @overload
 def cache[**Args, Result](
     function: Callable[Args, Result],
@@ -21,58 +44,156 @@ def cache[**Args, Result](
 
 
 @overload
-def cache[**Args, Result](
+def cache[**Args, Result, Key: Hashable](
     *,
-    limit: int = 1,
+    limit: int | None = None,
     expiration: float | None = None,
+    make_key: CacheMakeKey[Args, Key] | None = None,
 ) -> Callable[[Callable[Args, Result]], Callable[Args, Result]]: ...
 
 
-def cache[**Args, Result](
+@overload
+def cache[**Args, Result, Key](
+    *,
+    make_key: CacheMakeKey[Args, Key],
+    read: CacheRead[Key, Result],
+    write: CacheWrite[Key, Result],
+) -> Callable[
+    [Callable[Args, Coroutine[None, None, Result]]], Callable[Args, Coroutine[None, None, Result]]
+]: ...
+
+
+def cache[**Args, Result, Key](  # noqa: PLR0913
     function: Callable[Args, Result] | None = None,
     *,
-    limit: int = 1,
+    limit: int | None = None,
     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.
+    make_key: CacheMakeKey[Args, Key] | None = None,
+    read: CacheRead[Key, Result] | None = None,
+    write: CacheWrite[Key, Result] | None = None,
+) -> (
+    Callable[
+        [Callable[Args, Coroutine[None, None, Result]]],
+        Callable[Args, Coroutine[None, None, Result]],
+    ]
+    | Callable[[Callable[Args, Result]], Callable[Args, Result]]
+    | Callable[Args, Result]
+):
+    """
+    Memoize the result of a function using a configurable cache.
 
     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)
+    function : Callable[Args, Result] | None
+        The function to be memoized.
+        When used as a simple decorator (i.e., `@cache`), this is the decorated function.
+        Should be omitted when cache is called with configuration arguments.
+    limit : int | None
+        The maximum number of entries to keep in the cache.
+        Defaults to 1 if not specified.
+        Ignored when using custom cache implementations (read/write).
+    expiration : float | None
+        Time in seconds after which a cache entry expires and will be recomputed.
+        Defaults to None, meaning entries don't expire based on time.
+        Ignored when using custom cache implementations (read/write).
+    make_key : CacheMakeKey[Args, Key] | None
+        Function to generate a cache key from function arguments.
+        If None, uses a default implementation that handles most cases.
+        Required when using custom cache implementations (read/write).
+    read : CacheRead[Key, Result] | None
+        Custom asynchronous function to read values from cache.
+        Must be provided together with `write` and `make_key`.
+        Only available for async functions.
+    write : CacheWrite[Key, Result] | None
+        Custom asynchronous function to write values to cache.
+        Must be provided together with `read` and `make_key`.
+        Only available for async functions.
 
     Returns
     -------
-    Callable[[Callable[_Args, _Result]], Callable[_Args, _Result]] | Callable[_Args, _Result]
-        provided function wrapped in cache
+    Callable
+        If `function` is provided as a positional argument, returns the memoized function.
+        Otherwise returns a decorator that can be applied to a function to memoize it
+        with the given configuration.
+
+    Notes
+    -----
+    This decorator supports both synchronous and asynchronous functions.
+    The default implementation uses a simple in-memory LRU cache.
+    For asynchronous functions, you can provide custom cache implementations
+    via the `read` and `write` parameters.
+
+    The default cache is not thread-safe and should not be used in multi-threaded
+    applications without external synchronization.
+
+    Examples
+    --------
+    Simple usage as a decorator:
+
+    >>> @cache
+    ... def my_function(x: int) -> int:
+    ...     print("Function called")
+    ...     return x * 2
+    >>> my_function(5)
+    Function called
+    10
+    >>> my_function(5)  # Cache hit, function body not executed
+    10
+
+    With configuration parameters:
+
+    >>> @cache(limit=10, expiration=60.0)
+    ... def my_function(x: int) -> int:
+    ...     return x * 2
+
+    With custom cache for async functions:
+
+    >>> @cache(make_key=custom_key_maker, read=redis_read, write=redis_write)
+    ... async def fetch_data(user_id: str) -> dict:
+    ...     return await api_call(user_id)
     """
 
     def _wrap(function: Callable[Args, Result]) -> Callable[Args, Result]:
         if iscoroutinefunction(function):
-            return cast(
-                Callable[Args, Result],
-                _AsyncCache(
-                    function,
-                    limit=limit,
-                    expiration=expiration,
-                ),
-            )
+            if read is not None and write is not None and make_key is not None:
+                assert limit is None and expiration is None  # nosec: B101
+                return cast(
+                    Callable[Args, Result],
+                    _CustomCache(
+                        function,
+                        make_key=make_key,
+                        read=read,
+                        write=write,
+                    ),
+                )
+
+            else:
+                assert read is None and write is None  # nosec: B101
+                return cast(
+                    Callable[Args, Result],
+                    _AsyncCache(
+                        function,
+                        limit=limit if limit is not None else 1,
+                        expiration=expiration,
+                        make_key=cast(
+                            CacheMakeKey[Args, Hashable],
+                            make_key if make_key is not None else _default_make_key,
+                        ),
+                    ),
+                )
 
         else:
+            assert read is None and write is None, "Custom sync cache is not supported"  # nosec: B101
             return cast(
                 Callable[Args, Result],
                 _SyncCache(
                     function,
-                    limit=limit,
+                    limit=limit if limit is not None else 1,
                     expiration=expiration,
+                    make_key=cast(
+                        CacheMakeKey[Args, Hashable],
+                        make_key if make_key is not None else _default_make_key,
+                    ),
                 ),
             )
 
@@ -101,6 +222,7 @@ class _SyncCache[**Args, Result]:
         "_cached",
         "_function",
         "_limit",
+        "_make_key",
         "_next_expire_time",
     )
 
@@ -110,10 +232,13 @@ class _SyncCache[**Args, Result]:
         /,
         limit: int,
         expiration: float | None,
+        make_key: CacheMakeKey[Args, Hashable],
     ) -> None:
         self._function: Callable[Args, Result] = function
         self._cached: OrderedDict[Hashable, _CacheEntry[Result]] = OrderedDict()
         self._limit: int = limit
+        self._make_key: CacheMakeKey[Args, Hashable] = make_key
+
         if expiration := expiration:
 
             def next_expire_time() -> float | None:
@@ -135,27 +260,17 @@ class _SyncCache[**Args, Result]:
         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,
-                ),
-            )
+        assert owner is None and instance is None, "cache does not work for classes"  # nosec: B101
+        return self
 
     def __call__(
         self,
         *args: Args.args,
         **kwargs: Args.kwargs,
     ) -> Result:
-        key: Hashable = _make_key(
-            args=args,
-            kwds=kwargs,
-            typed=True,
+        key: Hashable = self._make_key(
+            *args,
+            **kwargs,
         )
 
         match self._cached.get(key):
@@ -164,7 +279,6 @@ class _SyncCache[**Args, Result]:
 
             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:
@@ -178,47 +292,11 @@ class _SyncCache[**Args, Result]:
         )
 
         if len(self._cached) > self._limit:
-            # if still running let it complete if able
+            # keep the size limit
             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]:
     __slots__ = (
@@ -233,6 +311,7 @@ class _AsyncCache[**Args, Result]:
         "_cached",
         "_function",
         "_limit",
+        "_make_key",
         "_next_expire_time",
     )
 
@@ -242,10 +321,13 @@ class _AsyncCache[**Args, Result]:
         /,
         limit: int,
         expiration: float | None,
+        make_key: CacheMakeKey[Args, Hashable],
     ) -> None:
         self._function: Callable[Args, Coroutine[None, None, Result]] = function
-        self._cached: OrderedDict[Hashable, _CacheEntry[Task[Result]]] = OrderedDict()
+        self._cached: OrderedDict[Hashable, _CacheEntry[Result]] = OrderedDict()
         self._limit: int = limit
+        self._make_key: CacheMakeKey[Args, Hashable] = make_key
+
         if expiration := expiration:
 
             def next_expire_time() -> float | None:
@@ -267,28 +349,17 @@ class _AsyncCache[**Args, Result]:
         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,
-                ),
-            )
+        assert owner is None and instance is None, "cache does not work for classes"  # nosec: B101
+        return self
 
     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,
+        key: Hashable = self._make_key(
+            *args,
+            **kwargs,
         )
 
         match self._cached.get(key):
@@ -297,60 +368,88 @@ class _AsyncCache[**Args, Result]:
 
             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])
+                    return entry[0]
 
-        task: Task[Result] = loop.create_task(self._function(*args, **kwargs))  # pyright: ignore[reportCallIssue]
+        result: Result = await self._function(*args, **kwargs)
         self._cached[key] = _CacheEntry(
-            value=task,
+            value=result,
             expire=self._next_expire_time(),
         )
         if len(self._cached) > self._limit:
-            # if still running let it complete if able
+            # keep the size limit
             self._cached.popitem(last=False)
 
-        return await shield(task)
+        return result
+
 
-    async def __method_call__(
+class _CustomCache[**Args, Result, Key]:
+    __slots__ = (
+        "__annotations__",
+        "__defaults__",
+        "__doc__",
+        "__globals__",
+        "__kwdefaults__",
+        "__name__",
+        "__qualname__",
+        "__wrapped__",
+        "_expiration",
+        "_function",
+        "_make_key",
+        "_read",
+        "_write",
+    )
+
+    def __init__(
+        self,
+        function: Callable[Args, Coroutine[None, None, Result]],
+        /,
+        make_key: CacheMakeKey[Args, Key],
+        read: CacheRead[Key, Result],
+        write: CacheWrite[Key, Result],
+    ) -> None:
+        self._function: Callable[Args, Coroutine[None, None, Result]] = function
+        self._make_key: CacheMakeKey[Args, Key] = make_key
+        self._read: CacheRead[Key, Result] = read
+        self._write: CacheWrite[Key, Result] = write
+
+        # mimic function attributes if able
+        mimic_function(function, within=self)
+
+    async def __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,
+        key: Key = self._make_key(
+            *args,
+            **kwargs,
         )
 
-        match self._cached.get(key):
+        match await self._read(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
+                result: Result = await self._function(*args, **kwargs)
+                ctx.spawn(  # write the value asnychronously
+                    self._write,
+                    key=key,
+                    value=result,
+                )
 
-                else:
-                    self._cached.move_to_end(key)
-                    return await shield(entry[0])
+                return result
 
-        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(),
-        )
+            case entry:
+                return entry
 
-        if len(self._cached) > self._limit:
-            # if still running let it complete if able
-            self._cached.popitem(last=False)
 
-        return await shield(task)
+def _default_make_key[**Args](
+    *args: Args.args,
+    **kwargs: Args.kwargs,
+) -> Hashable:
+    return _make_key(
+        args=args,
+        kwds=kwargs,
+        typed=True,
+    )

{haiway-0.12.1.dist-info → haiway-0.13.0.dist-info}/METADATA

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: haiway
-Version: 0.12.1
+Version: 0.13.0
 Summary: Framework for dependency injection and state management within structured concurrency model.
 Project-URL: Homepage, https://miquido.com
 Project-URL: Repository, https://github.com/miquido/haiway.git
 Maintainer-email: Kacper Kaliński <kacper.kalinski@miquido.com>
 License: MIT License
         
-        Copyright (c) 2024 Miquido
+        Copyright (c) 2024-2025 Miquido
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
@@ -40,12 +40,12 @@ Requires-Dist: pyright~=1.1; extra == 'dev'
 Requires-Dist: pytest-asyncio~=0.23; extra == 'dev'
 Requires-Dist: pytest-cov~=4.1; extra == 'dev'
 Requires-Dist: pytest~=7.4; extra == 'dev'
-Requires-Dist: ruff~=0.9; extra == 'dev'
+Requires-Dist: ruff~=0.11; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # 🚗 haiway 🚕 🚚 🚙
 
-haiway is a framework helping to build better project codebase by leveraging concepts of structured concurrency and functional programming.
+haiway is a framework designed to facilitate the development of applications using the functional programming paradigm combined with structured concurrency concepts. Unlike traditional object-oriented frameworks, haiway emphasizes immutability, pure functions, and context-based state management, enabling developers to build scalable and maintainable applications. By leveraging context managers combined with context vars, haiway ensures safe state propagation in concurrent environments and simplifies dependency injection through function implementation propagation.
 
 ## 🖥️ Install
 
@@ -65,7 +65,7 @@ We welcome any feedback and suggestions! Feel free to open an issue or pull requ
 
 MIT License
 
-Copyright (c) 2024 Miquido
+Copyright (c) 2024-2025 Miquido
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{haiway-0.12.1.dist-info → haiway-0.13.0.dist-info}/RECORD

@@ -6,12 +6,12 @@ haiway/context/disposables.py,sha256=vcsh8jRaJ8Q1ob7oh5LsrSPw9f5AMTcaD_p_Gb7tXAI
 haiway/context/identifier.py,sha256=lz-FuspOtsaEsfb7QPrEVWYfbcMJgd3A6BGG3kLbaV0,3914
 haiway/context/logging.py,sha256=F3dr6MLjodg3MX5WTInxn3r3JuihG-giBzumI0GGUQw,5590
 haiway/context/metrics.py,sha256=N20XQtC8au_e_3iWrsZdej78YBEIWF44fdtWcZBWono,5223
-haiway/context/state.py,sha256=E3Z49XeE_EsXfYcPGtd-5_YLD5idK1WMMLZQ02of6cg,4554
+haiway/context/state.py,sha256=qskYoNwN5Ad0OgnyhL-PyGzTZltwVVdE9CEqWWn4lm8,4554
 haiway/context/tasks.py,sha256=J1BFQJis_15SIXbFclppxL-AOIThg2KS4SX8Hg_-YRY,2828
 haiway/context/types.py,sha256=VvJA7wAPZ3ISpgyThVguioYUXqhHf0XkPfRd0M1ERiQ,142
 haiway/helpers/__init__.py,sha256=8XRJWNhidWuBKqRZ1Hyc2xqt7DeWLcoOs2V-oexl8VY,579
 haiway/helpers/asynchrony.py,sha256=-yJsttRhKw0GgnzMc0FqIigS5UJl_G0YgkK12V5IzJg,6292
-haiway/helpers/caching.py,sha256=mz8IMKs6KWWVY62PosPbNQ9sGstC6xCWAAWLYZT2oSg,10132
+haiway/helpers/caching.py,sha256=iy2upZnlpLWc1FjQP0EjAu8j-Vl0yHZmIZ93K6Gc-yY,13232
 haiway/helpers/metrics.py,sha256=lCSvat3IrkmytFdqTvsqkVqYcVOK_bByfwYAe0hJIWg,13614
 haiway/helpers/retries.py,sha256=gIkyUlqJLDYaxIZd3qzeqGFY9y5Gp8dgZLlZ6hs8hoc,7538
 haiway/helpers/throttling.py,sha256=RfQn8GGPqTuPWzA1CJvZvb1s00vryVpo-eqz5EY9vD4,4150
@@ -36,7 +36,7 @@ haiway/utils/logs.py,sha256=oDsc1ZdqKDjlTlctLbDcp9iX98Acr-1tdw-Pyg3DElo,1577
 haiway/utils/mimic.py,sha256=BkVjTVP2TxxC8GChPGyDV6UXVwJmiRiSWeOYZNZFHxs,1828
 haiway/utils/noop.py,sha256=qgbZlOKWY6_23Zs43OLukK2HagIQKRyR04zrFVm5rWI,344
 haiway/utils/queue.py,sha256=Tk1bXvuNbEgapeC3-h_PYBASqVjhEoL8mUvtJnM29xI,4000
-haiway-0.12.1.dist-info/METADATA,sha256=9FgAnUCIw62Vr7u8MOmDbriyyURb-5aOQVSjv1qwMs0,3857
-haiway-0.12.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-haiway-0.12.1.dist-info/licenses/LICENSE,sha256=GehQEW_I1pkmxkkj3NEa7rCTQKYBn7vTPabpDYJlRuo,1063
-haiway-0.12.1.dist-info/RECORD,,
+haiway-0.13.0.dist-info/METADATA,sha256=vlLkeTbiQjf4ilZEEqTwrj18ZzgFzl_rPSHExuTxb0A,4299
+haiway-0.13.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+haiway-0.13.0.dist-info/licenses/LICENSE,sha256=3phcpHVNBP8jsi77gOO0E7rgKeDeu99Pi7DSnK9YHoQ,1069
+haiway-0.13.0.dist-info/RECORD,,

{haiway-0.12.1.dist-info → haiway-0.13.0.dist-info}/licenses/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Miquido
+Copyright (c) 2024-2025 Miquido
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.