moka-py 0.1.13__cp39-cp39-manylinux_2_17_s390x.manylinux2014_s390x.whl → 0.3.0__cp39-cp39-manylinux_2_17_s390x.manylinux2014_s390x.whl

moka_py/__init__.py

@@ -1,32 +1,57 @@
 import asyncio as _asyncio
-from functools import wraps as _wraps, _make_key
-from .moka_py import Moka, get_version as _get_version
+import inspect as _inspect
+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):
-    cache = Moka(maxsize, ttl, tti)
+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")
+        if _inspect.iscoroutinefunction(fn):
 
             @_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,51 +1,67 @@
-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")
 D = TypeVar("D")
 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,
+        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: ...
-
+    def set(
+        self,
+        key: K,
+        value: V,
+        ttl: int | float | None = None,
+        tti: int | float | None = None,
+    ) -> 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],
+        ttl: int | float | None = None,
+        tti: int | float | None = None,
+    ) -> V:
+        """Lookup or initialize a value for the key.
 
-    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.
+        If multiple threads call `get_with` with the same key, only one calls `initializer`,
+        the others wait until the value is set.
         """
 
-    def remove(self, key: K) -> Optional[V]: ...
-
+    @overload
+    def remove(self, key: K, default: D) -> V | D: ...
+    @overload
+    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,
+    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.3.0.dist-info/METADATA

@@ -0,0 +1,446 @@
+Metadata-Version: 2.4
+Name: moka-py
+Version: 0.3.0
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+License-File: LICENSE
+Summary: A high performance caching library for Python written in Rust
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/deliro/moka-py
+Project-URL: Issues, https://github.com/deliro/moka-py/issues
+Project-URL: Repository, https://github.com/deliro/moka-py
+
+# moka-py
+
+**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:** 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).
+- **Per-entry TTL / TTI:** Override the cache-wide TTL or TTI on individual entries.
+- **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
+
+Install with `uv`:
+
+```bash
+uv add moka-py
+```
+
+Or with `poetry`:
+
+```bash
+poetry add moka-py
+```
+
+Or with `pip`:
+
+```bash
+pip install moka-py
+```
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Features](#features)
+- [Usage](#usage)
+    - [Using moka_py.Moka](#using-moka_pymoka)
+    - [Per-entry TTL / TTI](#per-entry-ttl--tti)
+    - [@cached decorator](#as-a-decorator)
+    - [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)
+- [Eviction policies](#eviction-policies)
+- [Performance](#performance)
+- [License](#license)
+
+## Usage
+
+### Using moka_py.Moka
+
+```python
+from time import sleep
+from moka_py import Moka
+
+
+# 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=10.0, tti=0.1, policy="lru")
+
+# Insert a value.
+cache.set("key", [3, 2, 1])
+
+# Retrieve the value.
+assert cache.get("key") == [3, 2, 1]
+
+# Wait for 0.1+ seconds, and the entry will be automatically evicted.
+sleep(0.12)
+assert cache.get("key") is None
+```
+
+### Per-entry TTL / TTI
+
+By default, TTL and TTI are set once for the entire cache. You can also set them
+per entry by passing `ttl` and/or `tti` to `set()` or `get_with()`:
+
+```python
+from time import sleep
+from moka_py import Moka
+
+
+cache = Moka(100)
+
+cache.set("short-lived", "value", ttl=0.5)
+cache.set("session", {"user": "alice"}, ttl=3600.0)
+cache.set("idle-sensitive", "value", tti=1.0)
+cache.set("both", "value", ttl=60.0, tti=5.0)
+
+# Entries without per-entry ttl/tti never expire (unless the cache has global settings).
+cache.set("permanent", "value")
+
+sleep(0.6)
+assert cache.get("short-lived") is None  # expired after 0.5s
+assert cache.get("session") is not None  # still alive
+assert cache.get("permanent") is not None
+```
+
+`get_with()` accepts the same parameters:
+
+```python
+from moka_py import Moka
+
+
+cache = Moka(100)
+
+value = cache.get_with("key", lambda: "computed", ttl=30.0)
+```
+
+#### Concurrent `get_with` with different TTL / TTI
+
+`get_with()` guarantees that only **one** thread executes the initializer for a given key (stampede protection).
+When multiple threads call `get_with()` for the same key concurrently with **different** `ttl`/`tti` values,
+the thread that wins the race runs its initializer — and its `ttl`/`tti` values are stored with the entry.
+All other threads receive the same cached value and their `ttl`/`tti` parameters are **silently ignored**.
+
+```python
+import threading
+from moka_py import Moka
+
+
+cache = Moka(100)
+
+# Thread A: get_with("k", compute, ttl=1.0)
+# Thread B: get_with("k", compute, ttl=60.0)
+#
+# If thread A wins, the entry expires in 1 second.
+# If thread B wins, the entry expires in 60 seconds.
+# The loser's ttl is discarded — it is NOT merged or compared.
+```
+
+#### Interaction with cache-wide TTL / TTI
+
+When the cache is constructed with global `ttl` or `tti` **and** an entry specifies its own, the entry
+expires at whichever deadline comes **first**.
+
+> **WARNING**
+>
+> Per-entry TTL / TTI can only make an entry expire **sooner** than the cache-wide
+> policy, not later. This is a technical limitation of the underlying
+> [Moka](https://github.com/moka-rs/moka) library: global and per-entry expiration
+> are evaluated independently, and the earliest deadline wins.
+>
+> If you need entries with different lifetimes that can **exceed** a common default,
+> do not set global `ttl`/`tti` on the cache. Use per-entry values exclusively instead.
+
+```python
+from moka_py import Moka
+
+# Do this:
+cache = Moka(1000)
+cache.set("short", "v", ttl=60.0)
+cache.set("long", "v", ttl=300.0)  # works as expected
+
+# NOT this — "long" will still expire in 60 s:
+cache = Moka(1000, ttl=60.0)
+cache.set("long", "v", ttl=300.0)  # capped at 60 s by the global policy
+```
+
+```python
+from time import sleep
+from moka_py import Moka
+
+
+# Global TTL of 10 seconds.
+cache = Moka(100, ttl=10.0)
+
+# This entry will expire in 0.5 s (per-entry TTL wins, it is shorter).
+cache.set("fast", "value", ttl=0.5)
+
+# This entry keeps the global 10 s TTL (per-entry TTL=20 s is longer, so global wins).
+cache.set("slow", "value", ttl=20.0)
+
+sleep(0.6)
+assert cache.get("fast") is None
+assert cache.get("slow") is not None
+```
+
+### As a decorator
+
+moka-py can be used as a drop-in replacement for `@lru_cache()` with TTL + TTI support:
+
+```python
+from time import sleep
+from moka_py import cached
+
+
+calls = []
+
+
+@cached(maxsize=1024, ttl=5.0, tti=0.05)
+def f(x, y):
+    calls.append((x, y))
+    return x + y
+
+
+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
+
+Unlike `@lru_cache()`, `@moka_py.cached()` supports async functions:
+
+```python
+import asyncio
+from time import perf_counter
+from moka_py import cached
+
+
+calls = []
+
+
+@cached(maxsize=1024, ttl=5.0, tti=0.1)
+async def f(x, y):
+    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  # from cache
+elapsed = perf_counter() - start
+assert elapsed < 0.2
+assert len(calls) == 1
+```
+
+### Coalesce concurrent calls (wait_concurrent)
+
+`moka-py` can synchronize threads on keys
+
+```python
+import moka_py
+from typing import Any
+from time import sleep
+import threading
+from decimal import Decimal
+
+
+calls = []
+
+
+@moka_py.cached(ttl=5, wait_concurrent=True)
+def get_user(id_: int) -> dict[str, Any]:
+    calls.append(id_)
+    sleep(0.02)  # simulate an HTTP request (short for tests)
+    return {
+        "id": id_,
+        "first_name": "Jack",
+        "last_name": "Pot",
+    }
+
+
+def process_request(path: str, user_id: int) -> None:
+    user = get_user(user_id)
+    ...
+
+
+def charge_money(from_user_id: int, amount: Decimal) -> None:
+    user = get_user(from_user_id)
+    ...
+
+
+if __name__ == '__main__':
+    request_processing = threading.Thread(target=process_request, args=("/user/info/123", 123))
+    money_charging = threading.Thread(target=charge_money, args=(123, Decimal("3.14")))
+    request_processing.start()
+    money_charging.start()
+    request_processing.join()
+    money_charging.join()
+
+    # 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
+```
+
+### 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 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.
+
+Possible reasons:
+
+1. `"expired"`: The entry's expiration timestamp has passed.
+2. `"explicit"`: The entry was manually removed by the user (`.remove()` is called).
+3. `"replaced"`: The entry itself was not actually removed, but its value was replaced by the user (`.set()` is
+   called for an existing entry).
+4. `"size"`: The entry was evicted due to size constraints.
+
+```python
+from typing import Literal
+from moka_py import Moka
+from time import sleep
+
+
+def key_evicted(
+    k: str,
+    v: list[int],
+    cause: Literal["explicit", "size", "expired", "replaced"]
+):
+    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.5)
+moka.set("hello", [1, 2, 3])
+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) 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()`
+> 4) **Per-entry TTL / TTI and the eviction listener.** Per-entry expiry fires the
+>    listener with `"expired"` just like global TTL/TTI does. The notification is
+>    delivered lazily during subsequent cache operations (e.g. `get`, `set`) after
+>    the per-entry deadline passes — it is not instant.
+
+### Removing entries
+
+Remove an entry with `Moka.remove(key)`. It returns the previous value if present; otherwise `None`.
+
+```python
+from moka_py import Moka
+
+
+c = Moka(128)
+c.set("hello", "world")
+assert c.remove("hello") == "world"
+assert c.get("hello") is None
+```
+
+If `None` is a valid cached value, distinguish it from absence using `Moka.remove(key, default=...)`:
+
+```python
+from moka_py import Moka
+
+
+c = Moka(128)
+c.set("hello", None)
+assert c.remove("hello", default="WAS_NOT_SET") is None  # None was set explicitly
+
+# 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` 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
+
+
+c = Moka(128)
+my_list = [1, 2, 3]
+c.set("hello", my_list)
+still_the_same = c.get("hello")
+still_the_same.append(4)
+assert my_list == [1, 2, 3, 4]
+```
+
+## 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
+
+*Measured using MacBook Pro 14-inch, Nov 2024 with Apple M4 Pro processor and 24GiB RAM*
+
+```
+-------------------------------------------------------------------------------------------- benchmark: 9 tests -------------------------------------------------------------------------------------------
+Name (time in ns)                       Min                 Max                Mean            StdDev              Median               IQR            Outliers  OPS (Mops/s)            Rounds  Iterations
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+test_bench_remove                   68.1140 (1.0)       68.2812 (1.0)       68.1806 (1.0)      0.0671 (1.0)       68.1621 (1.0)      0.1000 (1.0)           1;0       14.6669 (1.0)           5    10000000
+test_bench_get[lru-False]           77.5126 (1.14)      78.2797 (1.15)      77.7823 (1.14)     0.2947 (4.39)      77.6792 (1.14)     0.2913 (2.91)          1;0       12.8564 (0.88)          5    10000000
+test_bench_get[tiny_lfu-False]      78.0985 (1.15)      78.8168 (1.15)      78.4920 (1.15)     0.2678 (3.99)      78.4868 (1.15)     0.3429 (3.43)          2;0       12.7401 (0.87)          5    10000000
+test_bench_get[lru-True]            89.1512 (1.31)      89.6459 (1.31)      89.4480 (1.31)     0.1910 (2.85)      89.5190 (1.31)     0.2458 (2.46)          2;0       11.1797 (0.76)          5    10000000
+test_bench_get[tiny_lfu-True]       91.4891 (1.34)      91.9214 (1.35)      91.6827 (1.34)     0.1867 (2.78)      91.7339 (1.35)     0.3141 (3.14)          2;0       10.9072 (0.74)          5    10000000
+test_bench_get_with                137.0672 (2.01)     137.8738 (2.02)     137.4143 (2.02)     0.3182 (4.74)     137.2839 (2.01)     0.4530 (4.53)          2;0        7.2773 (0.50)          5    10000000
+test_bench_set_str_key             354.1709 (5.20)     355.5768 (5.21)     354.9073 (5.21)     0.5631 (8.39)     355.0415 (5.21)     0.8900 (8.90)          2;0        2.8176 (0.19)          5     1408297
+test_bench_set[tiny_lfu]           355.6927 (5.22)     356.9633 (5.23)     356.3647 (5.23)     0.5645 (8.41)     356.4059 (5.23)     1.0390 (10.40)         2;0        2.8061 (0.19)          5     1405450
+test_bench_set[lru]                388.7005 (5.71)     389.5825 (5.71)     389.1170 (5.71)     0.3837 (5.72)     389.0796 (5.71)     0.6915 (6.92)          2;0        2.5699 (0.18)          5     1295615
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+```
+
+## License
+
+`moka-py` is distributed under the [MIT license](LICENSE).
+

moka_py-0.3.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+moka_py/__init__.py,sha256=WMkLJ34xVZ9eEnWsnfkOYxM_cWbo3IztW_3gUvmJ2V0,2318
+moka_py/__init__.pyi,sha256=1VMXf8_CKuik1EGAJzJ04kN0BgSZyPlxz7ceSKsTO5w,2297
+moka_py/moka_py.cpython-39-s390x-linux-gnu.so,sha256=2vGOYq5nDZrU6AFqy552WtElfHrn0HQgS6vPOdkr98E,705664
+moka_py/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+moka_py-0.3.0.dist-info/METADATA,sha256=cbEf4W_gAb5iDndFWBTdVZ_ApdxrhoGdGsAaxDFUZKU,15095
+moka_py-0.3.0.dist-info/WHEEL,sha256=XcaP7mD6aXEAQuMVCzXaOXD_TDNfWD8zFnptryRUioM,141
+moka_py-0.3.0.dist-info/licenses/LICENSE,sha256=CUj5ca53JXgIACVKNEOFOlbMWtxY4RXXj9cELIv2R04,1069
+moka_py-0.3.0.dist-info/RECORD,,

moka_py-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: maturin (1.11.5)
+Root-Is-Purelib: false
+Tag: cp39-cp39-manylinux_2_17_s390x
+Tag: cp39-cp39-manylinux2014_s390x

moka_py-0.1.13.dist-info/METADATA

@@ -1,224 +0,0 @@
-Metadata-Version: 2.4
-Name: moka-py
-Version: 0.1.13
-Classifier: Programming Language :: Rust
-Classifier: Programming Language :: Python :: Implementation :: CPython
-Classifier: Programming Language :: Python :: Implementation :: PyPy
-License-File: LICENSE
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
-
-# 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.
-
-## 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 the TinyLFU policy.
-- **Concurrency:** Optimized for high-performance, concurrent access in multi-threaded environments.
-
-## Installation
-
-You can install `moka-py` using `pip`:
-
-```bash
-pip install moka-py
-```
-
-## Quick Start
-
-```python
-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, 
-# the corresponding policy will not expire it.
-cache: Moka[str, list[int]] = Moka(capacity=100, ttl=30, tti=5.2)
-
-# Insert a value.
-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)
-assert cache.get("key") is None
-```
-
-moka-py can be used as a drop-in replacement for `@lru_cache()` with TTL + TTI support:
-
-```python
-from time import sleep
-from moka_py import cached
-
-
-@cached(maxsize=1024, ttl=10.0, tti=1.0)
-def f(x, y):
-    print("hard computations")
-    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)
-```
-
-But unlike `@lru_cache()`, `@moka_py.cached()` also supports async functions:
-
-```python
-import asyncio
-from time import perf_counter
-from moka_py import cached
-
-
-@cached(maxsize=1024, ttl=10.0, tti=1.0)
-async def f(x, y):
-    print("http request happening")
-    await asyncio.sleep(2.0)
-    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
-```
-
-moka-py can synchronize threads on keys
-
-```python
-import moka_py
-from typing import Any
-from time import sleep
-import threading
-from decimal import Decimal
-
-
-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
-    return {
-        "id": id_,
-        "first_name": "Jack",
-        "last_name": "Pot",
-    }
-
-
-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']})")
-    ...
-
-
-if __name__ == '__main__':
-    request_processing = threading.Thread(target=process_request, args=("/user/info/123", 123))
-    money_charging = threading.Thread(target=charge_money, args=(123, Decimal("3.14")))
-    request_processing.start()
-    money_charging.start()
-    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  
-```
-
-> **_ATTENTION:_**  `wait_concurrent` is not yet supported for async functions and will throw `NotImplementedError`
-
-## 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).
-
-There are 4 reasons why a key may be dropped:
-
-1. `"expired"`: The entry's expiration timestamp has passed.
-2. `"explicit"`: The entry was manually removed by the user (`.remove()` is called).
-3. `"replaced"`: The entry itself was not actually removed, but its value was replaced by the user (`.set()` is
-   called for an existing entry).
-4. `"size"`: The entry was evicted due to size constraints.
-
-```python
-from typing import Literal
-from moka_py import Moka
-from time import sleep
-
-
-def key_evicted(
-        k: str,
-        v: list[int],
-        cause: Literal["explicit", "size", "expired", "replaced"]
-):
-    print(f"entry {k}:{v} was evicted. {cause=}")
-
-
-moka: Moka[str, list[int]] = Moka(2, eviction_listener=key_evicted, ttl=0.1)
-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'
-```
-
-> **_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()`
-
-## Performance
-
-*Measured using MacBook Pro 2021 with Apple M1 Pro processor and 16GiB RAM*
-
-```
-------------------------------------------------------------------------------------------- benchmark: 5 tests -------------------------------------------------------------------------------------------
-Name (time in ns)                    Min                 Max                Mean             StdDev              Median                IQR            Outliers  OPS (Mops/s)            Rounds  Iterations
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-test_bench_get_non_existent     206.3389 (1.0)      208.9872 (1.0)      207.0240 (1.0)       1.1154 (4.27)     206.5119 (1.0)       0.9932 (2.73)          1;1        4.8304 (1.0)           5    10000000
-test_bench_get                  224.4981 (1.09)     229.1849 (1.10)     225.8305 (1.09)      1.9252 (7.37)     224.9832 (1.09)      1.8345 (5.05)          1;0        4.4281 (0.92)          5    10000000
-test_bench_get_with             248.2484 (1.20)     248.9123 (1.19)     248.5142 (1.20)      0.2612 (1.0)      248.5172 (1.20)      0.3634 (1.0)           2;0        4.0239 (0.83)          5     2020760
-test_bench_set_huge             676.6090 (3.28)     692.0143 (3.31)     683.5817 (3.30)      6.5151 (24.94)    684.8168 (3.32)     10.9585 (30.16)         2;0        1.4629 (0.30)          5     1000000
-test_bench_set                  723.4063 (3.51)     770.0967 (3.68)     738.1940 (3.57)     18.5167 (70.89)    733.0997 (3.55)     18.1077 (49.83)         1;0        1.3547 (0.28)          5     1000000
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-```
-
-## License
-
-moka-py is distributed under the [MIT license](LICENSE)
-

moka_py-0.1.13.dist-info/RECORD

@@ -1,8 +0,0 @@
-moka_py-0.1.13.dist-info/METADATA,sha256=0Ja8eVRcbkV6vATVmnrJRTBVJ4355CUsXQXV2Q10fnc,8331
-moka_py-0.1.13.dist-info/WHEEL,sha256=N-TSPwwwA2EqYtB-qCH5JjcTDipiRUuZBsjy1JM4bA4,125
-moka_py-0.1.13.dist-info/licenses/LICENSE,sha256=CUj5ca53JXgIACVKNEOFOlbMWtxY4RXXj9cELIv2R04,1069
-moka_py/__init__.py,sha256=7P0yGnJ8hNt5Hg_ndBEidy-8YWKyh6WhViNbBt7DOhI,1530
-moka_py/__init__.pyi,sha256=rlvQzwMrub2jTK8Mtr0tH246Fp86_oC1WZkZEYg9DRk,1534
-moka_py/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-moka_py/moka_py.cpython-39-s390x-linux-gnu.so,sha256=ExCwkun00Cmjn_j-pcBFB49lc09hemQ4jzbeiittT60,1059592
-moka_py-0.1.13.dist-info/RECORD,,

moka_py-0.1.13.dist-info/WHEEL

@@ -1,4 +0,0 @@
-Wheel-Version: 1.0
-Generator: maturin (1.7.8)
-Root-Is-Purelib: false
-Tag: cp39-cp39-manylinux_2_17_s390x.manylinux2014_s390x