moka-py 0.1.19__cp313-cp313t-musllinux_1_2_i686.whl → 0.2.4__cp313-cp313t-musllinux_1_2_i686.whl

moka_py/__init__.py

@@ -1,32 +1,56 @@
 import asyncio as _asyncio
-from functools import wraps as _wraps, _make_key
-from .moka_py import Moka, get_version as _get_version
+from functools import _make_key
+from functools import wraps as _wraps
+from typing import Any as _Any
 
+from .moka_py import Moka
+from .moka_py import get_version as _get_version
 
-__all__ = ["Moka", "cached", "VERSION"]
+__all__ = ["VERSION", "Moka", "cached"]
 
 VERSION = _get_version()
 
 
-def cached(maxsize=128, typed=False, *, ttl=None, tti=None, wait_concurrent=False, policy="tiny_lfu"):
+def cached(
+    maxsize=128,
+    typed=False,
+    *,
+    ttl=None,
+    tti=None,
+    wait_concurrent=False,
+    policy="tiny_lfu",
+):
+    """Cache decorator for sync and async functions with TTL/TTI and optional concurrent-waiting.
+
+    - For sync functions: returns cached value if present, otherwise computes and stores it.
+    - For async functions: returns an awaitable; with wait_concurrent=True a single shared task is created per key
+      so concurrent awaiters share the same result or exception.
+    """
     cache = Moka(maxsize, ttl=ttl, tti=tti, policy=policy)
     empty = object()
 
     def dec(fn):
         if _asyncio.iscoroutinefunction(fn):
-            if wait_concurrent:
-                raise NotImplementedError("wait_concurrent is not yet supported for async functions")
 
             @_wraps(fn)
             async def inner(*args, **kwargs):
                 key = _make_key(args, kwargs, typed)
-                maybe_value = cache.get(key, empty)
-                if maybe_value is not empty:
-                    return maybe_value
-                value = await fn(*args, **kwargs)
-                cache.set(key, value)
-                return value
+                if wait_concurrent:
+                    # Store a shared Task in cache while computation is in-flight
+                    def init() -> _Any:
+                        return _asyncio.create_task(fn(*args, **kwargs))
+
+                    task = cache.get_with(key, init)
+                    return await task
+                else:
+                    maybe_value = cache.get(key, empty)
+                    if maybe_value is not empty:
+                        return maybe_value
+                    value = await fn(*args, **kwargs)
+                    cache.set(key, value)
+                    return value
         else:
+
             @_wraps(fn)
             def inner(*args, **kwargs):
                 key = _make_key(args, kwargs, typed)

moka_py/__init__.pyi

@@ -1,5 +1,5 @@
-from typing import TypeVar, Optional, Generic, Hashable, Union, Callable, Any, overload, Literal
-
+from collections.abc import Callable, Hashable
+from typing import Any, Generic, Literal, TypeVar, overload
 
 K = TypeVar("K", bound=Hashable)
 V = TypeVar("V")
@@ -8,51 +8,48 @@ Fn = TypeVar("Fn", bound=Callable[..., Any])
 Cause = Literal["explicit", "size", "expired", "replaced"]
 Policy = Literal["tiny_lfu", "lru"]
 
-
 class Moka(Generic[K, V]):
     def __init__(
-            self,
-            capacity: int,
-            ttl: Optional[Union[int, float]] = None,
-            tti: Optional[Union[int, float]] = None,
-            eviction_listener: Optional[Callable[[K, V, Cause], None]] = None,
-            policy: Policy = "tiny_lfu",
+        self,
+        capacity: int,
+        ttl: int | float | None = None,
+        tti: int | float | None = None,
+        eviction_listener: Callable[[K, V, Cause], None] | None = None,
+        policy: Policy = "tiny_lfu",
     ): ...
-
     def set(self, key: K, value: V) -> None: ...
-
     @overload
-    def get(self, key: K, default: D) -> Union[V, D]: ...
-
+    def get(self, key: K, default: D) -> V | D: ...
     @overload
-    def get(self, key: K, default: Optional[D] = None) -> Optional[Union[V, D]]: ...
-
+    def get(self, key: K, default: D | None = None) -> V | D | None: ...
     def get_with(self, key: K, initializer: Callable[[], V]) -> V:
-        """
-        Lookups for a key in the cache and only if there is no value set, calls the `initializer`
-        function to set the key's value.
-        If multiple threads call `get_with` with the same key, only one of them calls
-        `initializer`, and the others wait until the value is set.
+        """Lookup or initialize a value for the key.
+
+        If multiple threads call `get_with` with the same key, only one calls `initializer`,
+        the others wait until the value is set.
         """
 
     @overload
-    def remove(self, key: K, default: D) -> Union[V, D]: ...
-
+    def remove(self, key: K, default: D) -> V | D: ...
     @overload
-    def remove(self, key: K, default: Optional[D] = None) -> Optional[Union[V, D]]: ...
-
+    def remove(self, key: K, default: D | None = None) -> V | D | None: ...
     def clear(self) -> None: ...
-
     def count(self) -> int: ...
 
-
 def cached(
-        maxsize: int = 128,
-        typed: bool = False,
-        *,
-        ttl: Optional[Union[int, float]] = None,
-        tti: Optional[Union[int, float]] = None,
-        wait_concurrent: bool = False,
-        policy: Policy = "tiny_lfu",
+    maxsize: int = 128,
+    typed: bool = False,
+    *,
+    ttl: int | float | None = None,
+    tti: int | float | None = None,
+    wait_concurrent: bool = False,
+    policy: Policy = "tiny_lfu",
 ) -> Callable[[Fn], Fn]:
-    ...
+    """Decorator for caching function results in a thread-safe in-memory cache.
+
+    - If the decorated function is synchronous: returns the cached value or computes and stores it.
+    - If the decorated function is asynchronous: returns an awaitable which yields the cached result.
+    - If wait_concurrent=True: concurrent calls with the same arguments wait on a single in-flight computation.
+      For async functions this is implemented via a shared asyncio.Task; all awaiters receive the same result
+      or the same exception.
+    """

{moka_py-0.1.19.dist-info → moka_py-0.2.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: moka-py
-Version: 0.1.19
+Version: 0.2.4
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
@@ -21,37 +21,32 @@ Project-URL: Issues, https://github.com/deliro/moka-py/issues
 
 # moka-py
 
-* * * 
-
-**moka-py** is a Python binding for the highly efficient [Moka](https://github.com/moka-rs/moka) caching library written
-in Rust. This library allows you to leverage the power of Moka's high-performance, feature-rich cache in your Python
-projects.
+**moka-py** is a Python binding to the [Moka](https://github.com/moka-rs/moka) cache written in Rust. It brings Moka’s high-performance, feature‑rich caching to Python.
 
 ## Features
 
-- **Synchronous Cache:** Supports thread-safe, in-memory caching for Python applications.
-- **TTL Support:** Automatically evicts entries after a configurable time-to-live (TTL).
-- **TTI Support:** Automatically evicts entries after a configurable time-to-idle (TTI).
-- **Size-based Eviction:** Automatically removes items when the cache exceeds its size limit using TinyLFU or LRU
-  policy.
-- **Concurrency:** Optimized for high-performance, concurrent access in multithreaded environments.
+- **Synchronous cache:** Thread-safe in-memory caching for Python.
+- **TTL:** Evicts entries after a configurable time to live (TTL).
+- **TTI:** Evicts entries after a configurable time to idle (TTI).
+- **Size-based eviction:** Removes items when capacity is exceeded using TinyLFU or LRU.
+- **Concurrency:** Optimized for high-throughput, concurrent access.
 - **Fully typed:** `mypy` and `pyright` friendly.
 
 ## Installation
 
-You can install `moka-py` using `uv`:
+Install with `uv`:
 
 ```bash
 uv add moka-py
 ```
 
-`poetry`:
+Or with `poetry`:
 
 ```bash
 poetry add moka-py
 ```
 
-Or, if you still stick to `pip` for some reason:
+Or with `pip`:
 
 ```bash
 pip install moka-py
@@ -64,8 +59,8 @@ pip install moka-py
 - [Usage](#usage)
     - [Using moka_py.Moka](#using-moka_pymoka)
     - [@cached decorator](#as-a-decorator)
-    - [async support](#async-support)
-    - [Do not call a function if another function is in progress](#do-not-call-a-function-if-another-function-is-in-progress)
+    - [Async support](#async-support)
+    - [Coalesce concurrent calls (wait_concurrent)](#coalesce-concurrent-calls-wait_concurrent)
     - [Eviction listener](#eviction-listener)
     - [Removing entries](#removing-entries)
 - [How it works](#how-it-works)
@@ -82,16 +77,16 @@ from time import sleep
 from moka_py import Moka
 
 
-# Create a cache with a capacity of 100 entries, with a TTL of 30 seconds
-# and a TTI of 5.2 seconds. Entries are always removed after 30 seconds
-# and are removed after 5.2 seconds if there are no `get`s happened for this time.
-# 
-# Both TTL and TTI settings are optional. In the absence of an entry, 
+# Create a cache with a capacity of 100 entries, with a TTL of 10.0 seconds
+# and a TTI of 0.1 seconds. Entries are always removed after 10 seconds
+# and are removed after 0.1 seconds if there are no `get`s happened for this time.
+#
+# Both TTL and TTI settings are optional. In the absence of an entry,
 # the corresponding policy will not expire it.
 
 # The default eviction policy is "tiny_lfu" which is optimal for most workloads,
 # but you can choose "lru" as well.
-cache: Moka[str, list[int]] = Moka(capacity=100, ttl=30, tti=5.2, policy="lru")
+cache: Moka[str, list[int]] = Moka(capacity=100, ttl=10.0, tti=0.1, policy="lru")
 
 # Insert a value.
 cache.set("key", [3, 2, 1])
@@ -99,8 +94,8 @@ cache.set("key", [3, 2, 1])
 # Retrieve the value.
 assert cache.get("key") == [3, 2, 1]
 
-# Wait for 5.2+ seconds, and the entry will be automatically evicted.
-sleep(5.3)
+# Wait for 0.1+ seconds, and the entry will be automatically evicted.
+sleep(0.12)
 assert cache.get("key") is None
 ```
 
@@ -113,16 +108,21 @@ from time import sleep
 from moka_py import cached
 
 
-@cached(maxsize=1024, ttl=10.0, tti=1.0)
+calls = []
+
+
+@cached(maxsize=1024, ttl=5.0, tti=0.05)
 def f(x, y):
-    print("hard computations")
+    calls.append((x, y))
     return x + y
 
 
-f(1, 2)  # calls computations
-f(1, 2)  # gets from the cache
-sleep(1.1)
-f(1, 2)  # calls computations (since TTI has passed)
+assert f(1, 2) == 3  # calls computations
+assert f(1, 2) == 3  # gets from the cache
+assert len(calls) == 1
+sleep(0.06)
+assert f(1, 2) == 3  # calls computations again (since TTI has passed)
+assert len(calls) == 2
 ```
 
 ### Async support
@@ -135,22 +135,27 @@ from time import perf_counter
 from moka_py import cached
 
 
-@cached(maxsize=1024, ttl=10.0, tti=1.0)
+calls = []
+
+
+@cached(maxsize=1024, ttl=5.0, tti=0.1)
 async def f(x, y):
-    print("http request happening")
-    await asyncio.sleep(2.0)
+    calls.append((x, y))
+    await asyncio.sleep(0.05)
     return x + y
 
 
 start = perf_counter()
 assert asyncio.run(f(5, 6)) == 11
-assert asyncio.run(f(5, 6)) == 11  # got from cache
-assert perf_counter() - start < 4.0
+assert asyncio.run(f(5, 6)) == 11  # from cache
+elapsed = perf_counter() - start
+assert elapsed < 0.2
+assert len(calls) == 1
 ```
 
-### Do not call a function if another function is in progress
+### Coalesce concurrent calls (wait_concurrent)
 
-moka-py can synchronize threads on keys
+`moka-py` can synchronize threads on keys
 
 ```python
 import moka_py
@@ -166,7 +171,7 @@ calls = []
 @moka_py.cached(ttl=5, wait_concurrent=True)
 def get_user(id_: int) -> dict[str, Any]:
     calls.append(id_)
-    sleep(0.3)  # simulation of HTTP request
+    sleep(0.02)  # simulate an HTTP request (short for tests)
     return {
         "id": id_,
         "first_name": "Jack",
@@ -176,13 +181,11 @@ def get_user(id_: int) -> dict[str, Any]:
 
 def process_request(path: str, user_id: int) -> None:
     user = get_user(user_id)
-    print(f"user #{user_id} came to {path}, their info is {user}")
     ...
 
 
 def charge_money(from_user_id: int, amount: Decimal) -> None:
     user = get_user(from_user_id)
-    print(f"charging {amount} money from user #{from_user_id} ({user['first_name']} {user['last_name']})")
     ...
 
 
@@ -194,20 +197,23 @@ if __name__ == '__main__':
     request_processing.join()
     money_charging.join()
 
-    # only one call occurred. without the `wait_concurrent` option, each thread would go for an HTTP request
-    # since no cache key was set
-    assert len(calls) == 1  
+    # Only one call occurred. Without `wait_concurrent`, each thread would issue its own HTTP request
+    # before the cache entry is set.
+    assert len(calls) == 1
 ```
 
-> **_ATTENTION:_**  `wait_concurrent` is not yet supported for async functions and will throw `NotImplementedError`
+### Async wait_concurrent
+
+When using `wait_concurrent=True` with async functions, `moka-py` creates a shared `asyncio.Task` per cache key. All
+concurrent callers `await` the same task and receive the same result or exception. This eliminates duplicate in-flight
+work for identical arguments.
 
 ### Eviction listener
 
-moka-py supports adding of an eviction listener that's called whenever a key is dropped
-from the cache for some reason. The listener must be a 3-arguments function `(key, value, cause)`. The arguments
-are passed as positional (not keyword).
+`moka-py` supports an eviction listener, called whenever a key is removed.
+The listener must be a three-argument function `(key, value, cause)` and uses positional arguments only.
 
-There are 4 reasons why a key may be dropped:
+Possible reasons:
 
 1. `"expired"`: The entry's expiration timestamp has passed.
 2. `"explicit"`: The entry was manually removed by the user (`.remove()` is called).
@@ -222,41 +228,37 @@ from time import sleep
 
 
 def key_evicted(
-        k: str,
-        v: list[int],
-        cause: Literal["explicit", "size", "expired", "replaced"]
+    k: str,
+    v: list[int],
+    cause: Literal["explicit", "size", "expired", "replaced"]
 ):
-    print(f"entry {k}:{v} was evicted. {cause=}")
+    events.append((k, v, cause))
+
+
+events: list[tuple[str, list[int], str]] = []
 
 
-moka: Moka[str, list[int]] = Moka(2, eviction_listener=key_evicted, ttl=0.1)
+moka: Moka[str, list[int]] = Moka(2, eviction_listener=key_evicted, ttl=0.5)
 moka.set("hello", [1, 2, 3])
-moka.set("hello", [3, 2, 1])
-moka.set("foo", [4])
-moka.set("bar", [])
-sleep(1)
-moka.get("foo")
-
-# will print
-# entry hello:[1, 2, 3] was evicted. cause='replaced'
-# entry bar:[] was evicted. cause='size'
-# entry hello:[3, 2, 1] was evicted. cause='expired'
-# entry foo:[4] was evicted. cause='expired'
+moka.set("hello", [3, 2, 1])  # replaced
+moka.set("foo", [4])  # expired
+moka.set("baz", "size")
+moka.remove("foo")  # explicit
+sleep(1.0)
+moka.get("anything")  # this will trigger eviction for expired
+
+causes = {c for _, _, c in events}
+assert causes == {"size", "expired", "replaced", "explicit"}, events
 ```
 
-> **_IMPORTANT NOTES_**:
-> 1. It's not guaranteed that the listener will be called just in time. Also, the underlying `moka` doesn't use any
-     background threads or tasks, hence, the listener is never called in "background"
-> 2. The listener must never raise any kind of `Exception`. If an exception is raised, it might be raised to any of the
-     moka-py method in any of the threads that call this method.
-> 3. The listener must be fast. Since it's called only when you're interacting with `moka-py` (via `.get()` / `.set()` /
-     etc.), the listener will slow down these operations. It's terrible idea to do some sort of IO in the listener. If
-     you need so, run a `ThreadPoolExecutor` somewhere and call `.submit()` inside of the listener or commit an async
-     task via `asyncio.create_task()`
+> IMPORTANT NOTES
+> 1) The listener is not called just-in-time. `moka` has no background threads or tasks; it runs only during cache operations.
+> 2) The listener must not raise exceptions. If it does, the exception may surface from any `moka-py` method on any thread.
+> 3) Keep the listener fast. Heavy work (especially I/O) will slow `.get()`, `.set()`, etc. Offload via `ThreadPoolExecutor.submit()` or `asyncio.create_task()`
 
 ### Removing entries
 
-An entry can be removed using `Moka.remove(key)`. If a value was set, it is returned; otherwise, `None` is returned.
+Remove an entry with `Moka.remove(key)`. It returns the previous value if present; otherwise `None`.
 
 ```python
 from moka_py import Moka
@@ -268,8 +270,7 @@ assert c.remove("hello") == "world"
 assert c.get("hello") is None
 ```
 
-In some cases you may want `None`s to be a valid cache value. In this case you need to distinguish between `None` as a
-value and `None` as the absence of a value. Use `Moka.remove(key, default=...)`:
+If `None` is a valid cached value, distinguish it from absence using `Moka.remove(key, default=...)`:
 
 ```python
 from moka_py import Moka
@@ -277,19 +278,18 @@ from moka_py import Moka
 
 c = Moka(128)
 c.set("hello", None)
-assert c.remove("hello", default="WAS_NOT_SET") is None  # None is returned since is was set 
+assert c.remove("hello", default="WAS_NOT_SET") is None  # None was set explicitly
 
-# Now entry with key "hello" doesn't exist so `default` argument is returned 
-assert c.remove("hello", default="WAS_NOT_SET") == "WAS_NOT_SET" 
+# Now the entry "hello" does not exist, so `default` is returned
+assert c.remove("hello", default="WAS_NOT_SET") == "WAS_NOT_SET"
 ```
 
 ## How it works
 
-`Moka` object stores Python object references
-(by [`INCREF`ing](https://docs.python.org/3/c-api/refcounting.html#c.Py_INCREF) `PyObject`s) and doesn't use
-serialization or deserialization. This means you can use any Python object as a value and any Hashable object as a
-key (`Moka` calls keys' `__hash__` magic methods). But also you need to remember that mutable objects stored in `Moka`
-are still mutable:
+`Moka` stores Python object references
+(by [`Py_INCREF`](https://docs.python.org/3/c-api/refcounting.html#c.Py_INCREF)) and does not serialize or deserialize values.
+You can use any Python object as a value and any hashable object as a key (`__hash__` is used).
+Mutable objects remain mutable:
 
 ```python
 from moka_py import Moka
@@ -305,8 +305,8 @@ assert my_list == [1, 2, 3, 4]
 
 ## Eviction policies
 
-moka-py uses the TinyLFU eviction policy as default, with LRU option. You can learn more about the
-policies [here](https://github.com/moka-rs/moka/wiki#admission-and-eviction-policies)
+`moka-py` uses TinyLFU by default, with an LRU option. Learn more in the
+[Moka wiki](https://github.com/moka-rs/moka/wiki#admission-and-eviction-policies).
 
 ## Performance
 
@@ -330,5 +330,5 @@ test_bench_set[lru]                637.3014 (6.32)     644.4533 (5.92)     640.3
 
 ## License
 
-moka-py is distributed under the [MIT license](LICENSE)
+`moka-py` is distributed under the [MIT license](LICENSE).
 

moka_py-0.2.4.dist-info/RECORD

@@ -0,0 +1,9 @@
+moka_py-0.2.4.dist-info/METADATA,sha256=e-jmd2RcuG_uvXEOaMjJCkLE6QHQR5FZzkkvEFy6wfQ,11475
+moka_py-0.2.4.dist-info/WHEEL,sha256=oHwEJ_sHUIKwY8lfSLMj5-lqV-wVA1FvC_ywV4lvspY,106
+moka_py-0.2.4.dist-info/licenses/LICENSE,sha256=CUj5ca53JXgIACVKNEOFOlbMWtxY4RXXj9cELIv2R04,1069
+moka_py.libs/libgcc_s-27e5a392.so.1,sha256=x5sO63liVwXxrjGGP371wB0RyQe1KEnIynYm82T0G0M,449745
+moka_py/__init__.py,sha256=yb0K713ikrp4a6raS0p16W_9CVX17ReTil-M8-rmjv0,2291
+moka_py/__init__.pyi,sha256=_mBsBklSY575Gxl-StCX7mv4QGugyh_Z47Rxnz0XlaE,2075
+moka_py/moka_py.cpython-313t-i386-linux-musl.so,sha256=qHkadq-eikRqLShneneHpaPKHLm8udLDfKI5SOg6oho,571845
+moka_py/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+moka_py-0.2.4.dist-info/RECORD,,

{moka_py-0.1.19.dist-info → moka_py-0.2.4.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: maturin (1.9.4)
+Generator: maturin (1.9.6)
 Root-Is-Purelib: false
 Tag: cp313-cp313t-musllinux_1_2_i686

moka_py-0.1.19.dist-info/RECORD

@@ -1,9 +0,0 @@
-moka_py-0.1.19.dist-info/METADATA,sha256=gywOXWmAzickgFshSpu0pcRFPM9NOIjVZR5j9xrKss0,12348
-moka_py-0.1.19.dist-info/WHEEL,sha256=NFo86IM_WtVR-TFY-Pc6byqaWwE8xyk54G9_i5f5pvE,106
-moka_py-0.1.19.dist-info/licenses/LICENSE,sha256=CUj5ca53JXgIACVKNEOFOlbMWtxY4RXXj9cELIv2R04,1069
-moka_py.libs/libgcc_s-27e5a392.so.1,sha256=x5sO63liVwXxrjGGP371wB0RyQe1KEnIynYm82T0G0M,449745
-moka_py/__init__.py,sha256=Vm6tQsXweLtjD_QjBSWtJRquv9g7wq3zrQZJ7EBQGko,1572
-moka_py/__init__.pyi,sha256=wfOnFVeRxogZpBwhUMWqlAVw_0yAa5xuCO28GJNTkGg,1777
-moka_py/moka_py.cpython-313t-i386-linux-musl.so,sha256=bYkbLhGaRL90NQG2MCv4_PImfWyVkeJQNzbi7g8OfRQ,571845
-moka_py/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-moka_py-0.1.19.dist-info/RECORD,,