moka-py 0.2.4__cp314-cp314-musllinux_1_2_aarch64.whl → 0.3.0__cp314-cp314-musllinux_1_2_aarch64.whl

moka_py/__init__.py

@@ -1,4 +1,5 @@
 import asyncio as _asyncio
+import inspect as _inspect
 from functools import _make_key
 from functools import wraps as _wraps
 from typing import Any as _Any
@@ -30,7 +31,7 @@ def cached(
     empty = object()
 
     def dec(fn):
-        if _asyncio.iscoroutinefunction(fn):
+        if _inspect.iscoroutinefunction(fn):
 
             @_wraps(fn)
             async def inner(*args, **kwargs):

moka_py/__init__.pyi

@@ -17,12 +17,24 @@ class Moka(Generic[K, V]):
         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) -> V | D: ...
     @overload
     def get(self, key: K, default: D | None = None) -> V | D | None: ...
-    def get_with(self, key: K, initializer: Callable[[], V]) -> V:
+    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.
 
         If multiple threads call `get_with` with the same key, only one calls `initializer`,

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: moka-py
-Version: 0.2.4
+Version: 0.3.0
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
@@ -16,8 +16,8 @@ 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: Repository, 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
 
@@ -28,6 +28,7 @@ Project-URL: Issues, https://github.com/deliro/moka-py/issues
 - **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.
@@ -58,6 +59,7 @@ pip install moka-py
 - [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)
@@ -99,6 +101,112 @@ 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:
@@ -255,6 +363,10 @@ assert causes == {"size", "expired", "replaced", "explicit"}, events
 > 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
 
@@ -310,21 +422,21 @@ assert my_list == [1, 2, 3, 4]
 
 ## Performance
 
-*Measured using MacBook Pro 2021 with Apple M1 Pro processor and 16GiB RAM*
+*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                  100.8775 (1.0)      108.9191 (1.0)      102.6757 (1.0)      3.4992 (34.54)    101.0640 (1.0)      2.4234 (15.49)         1;1        9.7394 (1.0)           5    10000000
-test_bench_get[lru-False]          112.8452 (1.12)     113.0924 (1.04)     112.9415 (1.10)     0.1013 (1.0)      112.9176 (1.12)     0.1565 (1.0)           1;0        8.8541 (0.91)          5    10000000
-test_bench_get[tiny_lfu-False]     135.0147 (1.34)     135.6069 (1.25)     135.2916 (1.32)     0.2246 (2.22)     135.2849 (1.34)     0.3164 (2.02)          2;0        7.3914 (0.76)          5    10000000
-test_bench_get[lru-True]           135.1628 (1.34)     135.7813 (1.25)     135.4712 (1.32)     0.2231 (2.20)     135.4765 (1.34)     0.2477 (1.58)          2;0        7.3816 (0.76)          5    10000000
-test_bench_get[tiny_lfu-True]      135.2461 (1.34)     135.6612 (1.25)     135.4463 (1.32)     0.1802 (1.78)     135.4026 (1.34)     0.3192 (2.04)          2;0        7.3830 (0.76)          5    10000000
-test_bench_get_with                290.5307 (2.88)     291.0418 (2.67)     290.8393 (2.83)     0.1893 (1.87)     290.8867 (2.88)     0.1873 (1.20)          2;0        3.4383 (0.35)          5    10000000
-test_bench_set[tiny_lfu]           515.7514 (5.11)     518.6080 (4.76)     517.4876 (5.04)     1.1196 (11.05)    517.6572 (5.12)     1.5465 (9.88)          2;0        1.9324 (0.20)          5     1912971
-test_bench_set_str_key             516.1032 (5.12)     533.7330 (4.90)     525.7461 (5.12)     6.3386 (62.57)    526.8491 (5.21)     6.1052 (39.01)         2;0        1.9021 (0.20)          5     1918471
-test_bench_set[lru]                637.3014 (6.32)     644.4533 (5.92)     640.3571 (6.24)     2.8981 (28.61)    639.8821 (6.33)     4.6131 (29.48)         2;0        1.5616 (0.16)          5     1581738
+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
 -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 ```
 

moka_py-0.3.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+moka_py/__init__.py,sha256=WMkLJ34xVZ9eEnWsnfkOYxM_cWbo3IztW_3gUvmJ2V0,2318
+moka_py/__init__.pyi,sha256=1VMXf8_CKuik1EGAJzJ04kN0BgSZyPlxz7ceSKsTO5w,2297
+moka_py/moka_py.cpython-314-aarch64-linux-musl.so,sha256=M6VVLCU-1100wiOZBfM5fV0Ofzky8fov1sLXI6Id26c,723625
+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=wfa3QoSp_ZyLpGod_VyrFzSaMcf2FS-0HgJ4XxFA7a8,109
+moka_py-0.3.0.dist-info/licenses/LICENSE,sha256=CUj5ca53JXgIACVKNEOFOlbMWtxY4RXXj9cELIv2R04,1069
+moka_py.libs/libgcc_s-0bf60adc.so.1,sha256=9fhX5YpiwtHdsiLMLz77Pw9jjIEGriteV7UOUrrwvpk,527681
+moka_py-0.3.0.dist-info/RECORD,,

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

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: maturin (1.9.6)
+Generator: maturin (1.11.5)
 Root-Is-Purelib: false
 Tag: cp314-cp314-musllinux_1_2_aarch64

moka_py-0.2.4.dist-info/RECORD

@@ -1,9 +0,0 @@
-moka_py-0.2.4.dist-info/METADATA,sha256=e-jmd2RcuG_uvXEOaMjJCkLE6QHQR5FZzkkvEFy6wfQ,11475
-moka_py-0.2.4.dist-info/WHEEL,sha256=3dJIuQYj1xffw_5TULgTDxRmdRwYLHfh8CpBkgcXhHU,108
-moka_py-0.2.4.dist-info/licenses/LICENSE,sha256=CUj5ca53JXgIACVKNEOFOlbMWtxY4RXXj9cELIv2R04,1069
-moka_py.libs/libgcc_s-39080030.so.1,sha256=fIO6GHOh8Ft9CR0Geu7wSUb9Xnl122iTtrxQQ9TAkTQ,789673
-moka_py/__init__.py,sha256=yb0K713ikrp4a6raS0p16W_9CVX17ReTil-M8-rmjv0,2291
-moka_py/__init__.pyi,sha256=_mBsBklSY575Gxl-StCX7mv4QGugyh_Z47Rxnz0XlaE,2075
-moka_py/moka_py.cpython-314-aarch64-linux-musl.so,sha256=9j33ov1lpNrOOTf2Nruba3QNfEibSXKgitB2BoOVYog,723609
-moka_py/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-moka_py-0.2.4.dist-info/RECORD,,