onecache 0.9.0__cp313-cp313-win32.whl

onecache/__init__.py

@@ -0,0 +1,122 @@
+"""Onecache main module."""
+
+import os
+from functools import update_wrapper
+from typing import Optional
+
+if os.environ.get("ONECACHE_NO_EXTENSIONS"):
+    from onecache._core import CacheValue, ExpirableCache, LRUCache, monotonic
+
+    COMPILED = False
+else:
+    try:
+        from onecache._ccore import CacheValue, ExpirableCache, LRUCache, monotonic
+
+        COMPILED = True
+    except ImportError:
+        from onecache._core import CacheValue, ExpirableCache, LRUCache, monotonic
+
+        COMPILED = False
+
+__all__ = [
+    "AsyncCacheDecorator",
+    "CacheDecorator",
+    "CacheValue",
+    "COMPILED",
+    "ExpirableCache",
+    "LRUCache",
+    "monotonic",
+]
+
+_MISSING = object()
+
+
+class CacheDecorator:
+    """Decorator for ExpirableCache"""
+
+    def __init__(
+        self,
+        maxsize=512,
+        ttl: Optional[int] = None,
+        skip_args: bool = False,
+        cache_class=LRUCache,
+        refresh_ttl: Optional[bool] = False,
+        thread_safe: Optional[bool] = False,
+        max_mem_size: Optional[int] = None,
+    ):
+        """
+        Args:
+            * **maxsize (int)**: Maximun number of items to be cached. default: 512
+            * **ttl (int)**: time to expire in milliseconds, if None, it does not expire. default: None
+            * **skip_args (bool)**: apply cache as the function doesn't have any arguments, default: False
+            * **cache_class (class)**: Class to use for cache instance. default: LRUCache
+            * **refresh_ttl (bool)**: if cache with ttl, This flag makes key expiration timestamp to be
+                refresh per access. default: False
+            * **thread_safe (bool)**: tell decorator to use thread safe lock. default=False
+            * **max_mem_size (int)**: max mem size inside cache structure. default=None which means no limit.
+                For pypy this value is ignored as the objects can change by the JIT compilation.
+        """
+        self.cache = cache_class(
+            maxsize,
+            ttl,
+            refresh_ttl=refresh_ttl,
+            thread_safe=thread_safe,
+            max_mem_size=max_mem_size,
+        )
+        self.maxsize = maxsize
+        self.skip_args = skip_args
+        self._fast = type(self.cache) in (ExpirableCache, LRUCache)
+
+    def __call__(self, func):
+        cache = self.cache
+        skip_args = self.skip_args
+
+        if self._fast:
+            return update_wrapper(cache._wrap(func, skip_args), func, updated=())
+
+        def wrapper(*args, **kwargs):
+            key = "any" if skip_args else cache.get_key(*args, **kwargs)
+            if key not in cache:
+                resp = func(*args, **kwargs)
+                cache.set(key, resp)
+                return resp
+            return cache.get(key)
+
+        wrapper.cache = cache
+
+        return update_wrapper(wrapper, func, updated=())
+
+
+class AsyncCacheDecorator(CacheDecorator):
+    """Async Decorator for ExpirableCache"""
+
+    def __call__(self, func):
+        cache = self.cache
+        skip_args = self.skip_args
+
+        if self._fast:
+            make_key = cache._make_key
+            lookup = cache._lookup
+            set_value = cache.set
+
+            async def async_wrapper(*args, **kwargs):
+                key = "any" if skip_args else make_key(args, kwargs)
+                value = lookup(key, _MISSING)
+                if value is _MISSING:
+                    value = await func(*args, **kwargs)
+                    set_value(key, value)
+                return value
+
+        else:
+
+            async def async_wrapper(*args, **kwargs):
+                key = "any" if skip_args else cache.get_key(*args, **kwargs)
+                if key not in cache:
+                    resp = await func(*args, **kwargs)
+                    cache.set(key, resp)
+                    return resp
+                return cache.get(key)
+
+        async_wrapper.cache = cache
+
+        return update_wrapper(async_wrapper, func, updated=())

onecache/_core.py

@@ -0,0 +1,310 @@
+"""Pure Python cache implementation, used on PyPy or when the extension is unavailable."""
+
+from collections import OrderedDict
+from contextlib import nullcontext
+from sys import getsizeof
+from threading import RLock
+from time import monotonic
+from types import MappingProxyType
+from typing import Any, Dict, Optional
+
+from onecache.utils import IS_PYPY
+
+INF = float("inf")
+_MISSING = object()
+
+
+class CacheValue:
+    """Cache entry holding the value, its expiration (monotonic seconds) and access count."""
+
+    __slots__ = ("value", "expire_at", "size", "access")
+
+    def __init__(self, value: Any, expire_at: Optional[float] = None):
+        self.value = value
+        self.expire_at = INF if expire_at is None else expire_at
+        self.size = 0
+        self.access = 0
+
+    def expired(self, now: Optional[float] = None) -> bool:
+        """Check if value is expired."""
+        return (monotonic() if now is None else now) > self.expire_at
+
+    def __eq__(self, other):
+        if not isinstance(other, CacheValue):
+            return NotImplemented
+        return self.value == other.value
+
+    __hash__ = None
+
+    def __reduce__(self):
+        return (_restore_value, (self.value, self.expire_at, self.size, self.access))
+
+
+def _restore_value(value, expire_at, size, access):
+    item = CacheValue(value, expire_at)
+    item.size = size
+    item.access = access
+    return item
+
+
+def _serialize(data: Any):
+    if type(data) is str:
+        return data
+    if isinstance(data, dict):
+        return ",".join([f"{key}={_serialize(val)}" for key, val in data.items()])
+    if isinstance(data, list):
+        return ",".join([_serialize(val) for val in data])
+    if isinstance(data, str):
+        return data
+    return str(data)
+
+
+def _make_key(args: tuple, kwargs: dict) -> str:
+    if not kwargs and len(args) == 1:
+        return _serialize(args[0])
+    parts = [_serialize(arg) for arg in args]
+    if kwargs:
+        parts.extend(f"{key}={_serialize(kwargs[key])}" for key in sorted(kwargs))
+    return "-".join(parts)
+
+
+class ExpirableCache:
+    """Cache with optional ttl, evicting the oldest inserted entry when full.
+
+    Params:
+        * **size (int)**: max items in dict. default=512
+        * **timeout (int)**: Timeout in milliseconds, if it is None,
+            there is no timeout. default=None
+        * **refresh_ttl (int)**: Refresh ttl anytime key is accessed. default=False
+        * **thread_safe (bool)**: Tell cache decorator to be thread safe. default=False
+        * **max_mem_size (int)**: max mem size inside cache structure. default=None which means no limit.
+            For pypy this value is ignored as the objects can change by the JIT compilation.
+    """
+
+    _lru = False
+
+    def __init__(
+        self,
+        size: int = 512,
+        timeout: Optional[int] = None,
+        refresh_ttl=False,
+        thread_safe=False,
+        max_mem_size: Optional[int] = None,
+    ):
+        self._data: Dict[Any, CacheValue] = OrderedDict()
+        self._expiry: Dict[Any, None] = OrderedDict()
+        self._timeout = timeout
+        self._ttl = timeout / 1000 if timeout and timeout > 0 else None
+        if size < 1:
+            raise ValueError("size must be at least 1")
+        self.size = size
+        self._max_mem_size = None if IS_PYPY else max_mem_size
+        self._current_size = 0
+        self.refresh_ttl = refresh_ttl
+        self._thread_safe = bool(thread_safe)
+        self._guard = RLock() if thread_safe else nullcontext()
+
+    @property
+    def cache(self):
+        """Read-only view of the cached entries."""
+        return MappingProxyType(self._data)
+
+    @property
+    def timeout(self):
+        """Ttl in milliseconds, None when entries do not expire."""
+        return self._timeout
+
+    @property
+    def max_mem_size(self):
+        """Max memory size of the cached entries, None when unlimited."""
+        return self._max_mem_size
+
+    @property
+    def current_size(self):
+        """Memory size of the cached entries, tracked only with max_mem_size."""
+        return self._current_size
+
+    @property
+    def thread_safe(self):
+        """Whether cache operations are guarded by a lock."""
+        return self._thread_safe
+
+    def get(self, key):
+        """Get value of key, None if missing or expired."""
+        with self._guard:
+            return self._lookup_unlocked(key, None)
+
+    def _lookup(self, key, default=None):
+        with self._guard:
+            return self._lookup_unlocked(key, default)
+
+    def _lookup_unlocked(self, key, default):
+        if self._expiry:
+            self._purge_expired(monotonic())
+        item = self._data.get(key)
+        if item is None:
+            return default
+        if item.expire_at != INF:
+            now = monotonic()
+            if now > item.expire_at:
+                self._remove_key(key)
+                return default
+            if self.refresh_ttl and self._ttl:
+                item.expire_at = now + self._ttl
+                try:
+                    self._expiry.move_to_end(key)
+                except KeyError:
+                    pass
+        if self._lru:
+            try:
+                self._data.move_to_end(key)
+            except KeyError:
+                pass
+            item.access += 1
+        return item.value
+
+    def set(self, key, data):
+        """Set value for key, evicting entries if needed.
+
+        With max_mem_size, a value bigger than the limit is not cached.
+        """
+        with self._guard:
+            self._set_unlocked(key, data)
+
+    def _set_unlocked(self, key, data):
+        now = monotonic() if self._ttl or self._expiry else 0.0
+        if self._expiry:
+            self._purge_expired(now)
+        size = 0
+        if self._max_mem_size:
+            size = getsizeof(key) + getsizeof(data)
+            if size > self._max_mem_size:
+                if key in self._data:
+                    self._remove_key(key)
+                return
+        if key in self._data:
+            self._remove_key(key)
+        elif self._data and len(self._data) >= self.size:
+            self._remove_key(next(iter(self._data)))
+
+        item = CacheValue(data)
+        if self._max_mem_size:
+            item.size = size
+            while self._data and self._current_size + size > self._max_mem_size:
+                self._remove_key(next(iter(self._data)))
+            self._current_size += size
+        self._data[key] = item
+        if self._ttl:
+            item.expire_at = now + self._ttl
+            self._expiry[key] = None
+
+    def _wrap(self, func, skip_args: bool = False):
+        lookup = self._lookup
+        set_value = self.set
+
+        def wrapper(*args, **kwargs):
+            key = "any" if skip_args else _make_key(args, kwargs)
+            value = lookup(key, _MISSING)
+            if value is _MISSING:
+                value = func(*args, **kwargs)
+                set_value(key, value)
+            return value
+
+        wrapper.cache = self
+        return wrapper
+
+    def _make_key(self, args: tuple, kwargs: dict) -> str:
+        return _make_key(args, kwargs)
+
+    def _purge_expired(self, now: float):
+        expiry = self._expiry
+        data = self._data
+        while expiry:
+            key = next(iter(expiry))
+            item = data.get(key)
+            if item is not None and now <= item.expire_at:
+                break
+            self._remove_key(key)
+
+    def _remove_key(self, key):
+        item = self._data.pop(key, None)
+        self._expiry.pop(key, None)
+        if item is not None and self._max_mem_size:
+            self._current_size -= item.size
+
+    def __contains__(self, key):
+        with self._guard:
+            item = self._data.get(key)
+            if item is None:
+                return False
+            if item.expire_at != INF and monotonic() > item.expire_at:
+                self._remove_key(key)
+                return False
+            return True
+
+    def __len__(self):
+        return len(self._data)
+
+    def __reduce__(self):
+        raise TypeError(f"cannot pickle {type(self).__name__!r} object")
+
+    def clear(self):
+        """Remove every entry."""
+        with self._guard:
+            entries = list(self._data.values())
+            self._data.clear()
+            self._expiry.clear()
+            self._current_size = 0
+        entries.clear()
+
+    def refresh_key_ttl(self, key: Any, milliseconds=None):
+        """Do refresh of key ttl, if present."""
+        ms = milliseconds or (self._timeout if self._ttl else None)
+        if not ms:
+            return
+        with self._guard:
+            item = self._data.get(key)
+            if item is None:
+                return
+            item.expire_at = monotonic() + ms / 1000
+            self._expiry[key] = None
+            self._expiry.move_to_end(key)
+
+    @classmethod
+    def get_key(cls, *args, **kwargs):
+        """Helper method to generate keys from *args, **kwargs."""
+        serialize = cls.serialize_key
+        kwargs_list = [f"{key}={serialize(kwargs[key])}" for key in sorted(kwargs)]
+        return "-".join([serialize(item) for item in list(args) + kwargs_list])
+
+    @classmethod
+    def serialize_key(cls, data: Any):
+        """Serialize a single argument into its key representation."""
+        if type(data) is str:
+            return data
+        if isinstance(data, dict):
+            return ",".join([f"{key}={cls.serialize_key(val)}" for key, val in data.items()])
+        if isinstance(data, list):
+            return ",".join([cls.serialize_key(val) for val in data])
+        if isinstance(data, str):
+            return data
+        return str(data)
+
+    def expire(self, *args, **kwargs):
+        """Usefull to expire any combination of *args, **kwargs."""
+        key = self.get_key(*args, **kwargs)
+        with self._guard:
+            if key in self._data:
+                self._remove_key(key)
+
+
+class LRUCache(ExpirableCache):
+    """Cache with optional ttl, evicting the least recently used entry when full."""
+
+    _lru = True
+
+    @property
+    def access(self):
+        """Get accesses as map."""
+        with self._guard:
+            return {key: val.access for key, val in self._data.items()}

onecache/cache_value.py

@@ -0,0 +1,3 @@
+from onecache import CacheValue
+
+__all__ = ["CacheValue"]

onecache/utils.py

@@ -0,0 +1,11 @@
+import datetime
+import platform
+import sys
+
+IS_PYPY = platform.python_implementation().lower().startswith("pypy")
+
+def utcnow():
+    if sys.version_info >= (3, 11):
+        return datetime.datetime.now(datetime.UTC)
+    else:
+        return datetime.datetime.utcnow()

onecache-0.9.0.dist-info/METADATA

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: onecache
+Version: 0.9.0
+Summary: Python cache for sync and async code
+Author-email: Johanderson Mogollon <johander1822@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/sonic182/onecache
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Cython
+Classifier: Programming Language :: Python :: 3.8
+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: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Dynamic: license
+
+
+[![Coverage Status](https://coveralls.io/repos/github/sonic182/onecache/badge.svg?branch=master)](https://coveralls.io/github/sonic182/onecache?branch=master)
+![github status](https://github.com/sonic182/onecache/actions/workflows/python.yml/badge.svg)
+# OneCache
+
+Python cache for sync and async code.
+
+Cache uses an LRU algorithm and can optionally set TTLs per entry.
+
+On CPython the cache core is a compiled Cython extension (prebuilt wheels for Linux, macOS and Windows on x86_64 and ARM64). On PyPy, or on platforms without a prebuilt wheel, it falls back to an equivalent pure Python implementation. `onecache.COMPILED` tells which one is in use.
+
+Tested automatically on CPython 3.10 and 3.14 and PyPy 3.11 across Linux, macOS, and Windows on x86_64 and ARM64 (see the workflow badge). Python 3.8 and 3.9 are still installable and get prebuilt wheels, but are no longer part of the test matrix.
+
+# Usage
+
+```python
+from onecache import CacheDecorator
+from onecache import AsyncCacheDecorator
+
+
+class Counter:
+    def __init__(self, count=0):
+        self.count = count
+
+
+@pytest.mark.asyncio
+async def test_async_cache_counter():
+    """Test async cache, counter case."""
+    counter = Counter()
+
+    @AsyncCacheDecorator()
+    async def mycoro(counter: Counter):
+        counter.count += 1
+        return counter.count
+
+    assert 1 == (await mycoro(counter))
+    assert 1 == (await mycoro(counter))
+
+
+def test_cache_counter():
+    """Test async cache, counter case."""
+    counter = Counter()
+
+    @CacheDecorator()
+    def sample(counter: Counter):
+        counter.count += 1
+        return counter.count
+
+    assert 1 == (sample(counter))
+    assert 1 == (sample(counter))
+```
+
+Decorator classes supports the following arguments
+
+* **maxsize (int)**: Maximun number of items to be cached. default: 512
+* **ttl (int)**: time to expire in milliseconds, if None, it does not expire. default: None
+* **skip_args (bool)**: apply cache as the function doesn't have any arguments, default: False
+* **cache_class (class)**: Class to use for cache instance. default: LRUCache
+* **refresh_ttl (bool)**: if cache with ttl, This flag makes key expiration timestamp to be refresh per access. default: False
+* **thread_safe (bool)**: tell decorator to use thread safe lock. default=False
+* **max_mem_size (int)**: max mem size in bytes, as the sum of `sys.getsizeof(key) + sys.getsizeof(value)` of every entry (shallow sizes). default=None which means no limit. For pypy this value is ignored as the objects can change by the JIT compilation.
+
+If num of records exceds maxsize, it drops the least recently used one. With `max_mem_size`, a value bigger than the limit is not cached.
+
+Use `thread_safe=True` when the decorated function is called from several threads.
+
+The decorated function exposes its cache as `.cache`: `.cache.expire(*args, **kwargs)` drops one entry, `.cache.clear()` drops all of them, and `.cache.cache` is a read-only view of the entries.
+
+Set `ONECACHE_NO_EXTENSIONS` to any non-empty value to force the pure Python implementation. If the extension failed to build when installing from source (e.g. no compiler), pip may keep reusing that pure Python build from its cache; reinstall with `pip install --no-cache-dir --force-reinstall onecache` after installing a compiler.
+
+
+# Development
+
+Install dependencies with Poetry (includes dev + test groups):
+```bash
+poetry install --with test,dev
+```
+
+Build the Cython extension in place (needed after any change to `onecache/_ccore.pyx`):
+```bash
+make build_ext
+```
+
+Run the test suite against the compiled and the pure Python implementations:
+```bash
+poetry run pytest
+ONECACHE_NO_EXTENSIONS=1 poetry run pytest
+```
+
+`onecache/_ccore.pyx` and `onecache/_core.py` implement the same API and must be kept in sync.
+
+# Releasing
+
+Pull requests only build cp310 and cp314 wheels, so first run the `Wheels` workflow by hand on `master` (Actions → Wheels → Run workflow) to build and test every Python version. Then bump `version` in `pyproject.toml` and push a tag with the same value (e.g. `0.9.0`). The `Wheels` workflow builds the wheels with cibuildwheel, the sdist and a pure Python fallback wheel, and publishes them to PyPI through trusted publishing. That needs a `pypi` environment in the GitHub repository settings and a trusted publisher on PyPI for this repository, workflow `wheels.yml` and environment `pypi`.
+
+Lint and format checks:
+```bash
+poetry run flake8
+poetry run autopep8 --in-place --recursive onecache tests
+```
+
+# Contribute
+
+1. Fork
+2. create a branch `feature/your_feature`
+3. commit - push - pull request
+
+Thanks :)

onecache-0.9.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+onecache/__init__.py,sha256=2U27qdtNKwZ0rXbjV2Lfzpx5LA4kKH0_GoUSPZQAaR4,4044
+onecache/_ccore.cp313-win32.pyd,sha256=UYPwwahS9KJPULKVZ8xzNwxPuihVJ8FDHYJg02r_3lI,106496
+onecache/_core.py,sha256=X_dMV_BlijwL7Nuvk9gtTpYRfSUSSW-ao_13HInK8PI,10451
+onecache/cache_value.py,sha256=9cLTkNHjQxlaVydUbS1UlDfuoiU2y_FRtMQOdsVrnvU,61
+onecache/utils.py,sha256=KyWmvw_lDVCvcFmD4qGzHOFa1yv7I02fem37jpsVzTo,279
+onecache-0.9.0.dist-info/METADATA,sha256=1baoMYJhRY7EV81UYQv0_J3L8FntNog14IfDsfRLeSg,5743
+onecache-0.9.0.dist-info/WHEEL,sha256=9z4P_Kq9LAX0eTloa6Af3pe3LKOxNzaw-XoJA4vn4Ao,97
+onecache-0.9.0.dist-info/top_level.txt,sha256=e1pCmlJnfcMBz3KIqLPb37lC1a2bYAZgXhfCfvFHriw,9
+onecache-0.9.0.dist-info/RECORD,,

onecache-0.9.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: false
+Tag: cp313-cp313-win32
+

onecache-0.9.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+onecache