ttl-cache-decorator 0.1.2__py3-none-any.whl

ttl_cache/__init__.py

@@ -0,0 +1 @@
+from ._ttl_lru import ttl_lru_cache, TTLCachedFunction  # noqa

ttl_cache/_ttl_lru.py

@@ -0,0 +1,83 @@
+import functools
+import random
+import time
+from collections.abc import Callable
+from functools import lru_cache, wraps
+from typing import Any, Protocol, cast
+
+
+class TTLCachedFunction[**P, R](Protocol):
+    """Same signature as the wrapped function, plus ``lru_cache``'s helpers."""
+
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> R: ...
+    def cache_info(self) -> functools._CacheInfo: ...
+    def cache_clear(self) -> None: ...
+
+
+def ttl_lru_cache[**P, R](
+    ttl: float = 60,
+    jitter: float = 0,
+    maxsize: int | None = 128,
+    typed: bool = False,
+) -> Callable[[Callable[P, R]], TTLCachedFunction[P, R]]:
+    """A decorator that works like ``lru_cache`` but with a time to live (ttl).
+
+    Under the hood it still uses ``lru_cache``, but the cached call receives an
+    extra positional-only ``time_bucket`` argument::
+
+        time_bucket = int((time.monotonic() + offset) // ttl)
+
+    An entry stays "alive" while the bucket value is unchanged and expires when
+    the bucket rolls over. ``offset`` is drawn once per decorated function from
+    ``random.uniform(0, jitter)``, so different functions (or processes) expire
+    at different moments instead of all at once.
+
+    Args:
+        ttl: Time to live in seconds. Defaults to 60.
+        jitter: Max random offset in seconds applied to the bucket boundaries.
+            Defaults to 0.
+        maxsize: Max size of the cache, or ``None`` for unbounded. Defaults to 128.
+        typed: Whether argument types are part of the cache key. Defaults to False.
+
+    Returns:
+        A decorator that wraps a function in a TTL-aware LRU cache. The wrapped
+        function keeps its signature and exposes ``cache_info`` and
+        ``cache_clear``.
+
+    Raises:
+        ValueError: If ``ttl`` is not positive or ``jitter`` is negative.
+
+    Example:
+        >>> @ttl_lru_cache(ttl=30, jitter=5)
+        ... def fetch(key: str) -> str:
+        ...     return key.upper()
+    """
+    if ttl <= 0:
+        raise ValueError(f"ttl must be positive, got {ttl!r}")
+    if jitter < 0:
+        raise ValueError(f"jitter must be non-negative, got {jitter!r}")
+
+    def decorator(func: Callable[P, R]) -> TTLCachedFunction[P, R]:
+        offset = random.uniform(0, jitter)
+
+        @lru_cache(maxsize=maxsize, typed=typed)
+        def cached_with_time(_time_bucket: int, /, *args: Any, **kwargs: Any) -> R:
+            return func(*args, **kwargs)
+
+        # lru_cache types its arguments as Hashable, which P.args/P.kwargs can't
+        # be proven to be. Unhashable arguments still raise TypeError at call
+        # time, exactly as with plain lru_cache.
+        call_cached = cast(Callable[..., R], cached_with_time)
+
+        @wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            time_bucket = int((time.monotonic() + offset) // ttl)
+            return call_cached(time_bucket, *args, **kwargs)
+
+        wrapper.__dict__.update(
+            cache_info=cached_with_time.cache_info,
+            cache_clear=cached_with_time.cache_clear,
+        )
+        return cast(TTLCachedFunction[P, R], wrapper)
+
+    return decorator

ttl_cache_decorator-0.1.2.dist-info/METADATA

@@ -0,0 +1,58 @@
+Metadata-Version: 2.5
+Name: ttl-cache-decorator
+Version: 0.1.2
+Summary: LRU Cache Decorator with a Time to Live
+Project-URL: Changelog, https://github.com/Johandielangman/ttl-cache-decorator/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://johandielangman.github.io/ttl-cache-decorator/
+Project-URL: Issues, https://github.com/Johandielangman/ttl-cache-decorator/issues
+Project-URL: Source, https://github.com/Johandielangman/ttl-cache-decorator
+Author-email: Johandielangman <johan@datatreehouse.org>
+License-Expression: MIT
+License-File: LICENSE.txt
+Classifier: Development Status :: 4 - Beta
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# TTL Cache
+
+[![PyPI - Version](https://img.shields.io/pypi/v/ttl-cache-decorator.svg)](https://pypi.org/project/ttl-cache-decorator)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/ttl-cache-decorator.svg)](https://pypi.org/project/ttl-cache-decorator)
+
+An LRU cache decorator with a time to live — like `functools.lru_cache`, but entries expire after a configurable number of seconds.
+
+## Installation
+
+```console
+pip install ttl-cache-decorator
+```
+
+## Usage
+
+```python
+from ttl_cache import ttl_lru_cache
+
+
+@ttl_lru_cache(ttl=30)
+def fetch_user(user_id: int) -> dict:
+    return {"id": user_id, "name": "Ada"}
+
+
+fetch_user(1)  # Calls the function
+fetch_user(1)  # Cache hit
+# ... 30 seconds later ...
+fetch_user(1)  # Expired — calls the function again
+```
+
+## License
+
+`ttl-cache-decorator` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

ttl_cache_decorator-0.1.2.dist-info/RECORD

@@ -0,0 +1,6 @@
+ttl_cache/__init__.py,sha256=2oTIuMAlfWiXoSNXjXX6n0tVkjjj8ewKR0YOhCYcYFI,63
+ttl_cache/_ttl_lru.py,sha256=3_aSt8sfby6TeDB67816W4i7Al9HtMzpQRrYi4hjXHs,3121
+ttl_cache_decorator-0.1.2.dist-info/METADATA,sha256=mdxWNUiKY4MhPSnxwYISgzPIIAnAxubMTu5ibXZHtps,2103
+ttl_cache_decorator-0.1.2.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+ttl_cache_decorator-0.1.2.dist-info/licenses/LICENSE.txt,sha256=9XrdCLKFXDpgek58eydUna_ucPUJuR75euMJp0_6f0I,1103
+ttl_cache_decorator-0.1.2.dist-info/RECORD,,

ttl_cache_decorator-0.1.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ttl_cache_decorator-0.1.2.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026-present Johandielangman <jghanekom2@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 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.