onecache 0.7.0__py3-none-any.whl

onecache/__init__.py

@@ -0,0 +1,241 @@
+"""Onecache main module."""
+
+from collections import OrderedDict
+from contextlib import contextmanager
+from datetime import timedelta
+from sys import getsizeof
+from threading import Lock
+from typing import Any, Dict, Optional
+
+from onecache.cache_value import CacheValue
+from onecache.utils import IS_PYPY, utcnow
+
+
+class ExpirableCache(object):
+    """Class used for custom cache decorator, dummy expirable cache based on dict structure.
+
+    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.
+    """
+
+    def __init__(
+        self,
+        size: int = 512,
+        timeout: Optional[int] = None,
+        refresh_ttl=False,
+        thread_safe=False,
+        max_mem_size: Optional[int] = None,
+    ):
+        self.cache: Dict[str, CacheValue] = OrderedDict()
+        self.timeout = timeout
+        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.lock = None
+        if thread_safe:
+            self.lock = Lock()
+
+    def set(self, key, data):
+        key_size = None
+        value = None
+        with self._scoped():
+            if len(self.cache) + 1 > self.size and key not in self.cache:
+                self._pop_one()
+
+            if self.timeout:
+                expire_at = utcnow() + timedelta(milliseconds=self.timeout)
+                value = CacheValue(data, expire_at)
+            else:
+                value = CacheValue(data)
+
+            if self.max_mem_size:
+                key_size = getsizeof(key)
+                # pop data if it will exceed max mem size
+                while (
+                    self.current_size + key_size + value.size > self.max_mem_size
+                    and len(self.cache) > 1
+                ):
+                    self._pop_one()
+            self.cache[key] = value
+
+            if self.max_mem_size:
+                self.current_size += key_size + value.size
+
+    def _pop_one(self):
+        key = next(iter(self.cache))
+        self._remove_key(key)
+
+    def get(self, key, fetch_value=True):
+        self._check_expired(key)
+        cache_value = self.cache.get(key)
+        if cache_value:
+            if self.refresh_ttl:
+                with self._scoped():
+                    self.refresh_key_ttl(key)
+            if fetch_value:
+                return cache_value.value
+            return cache_value
+
+    def _check_expired(self, key):
+        to_rm = []
+        if self.timeout:
+            for key, cache_value in self.cache.items():
+                if cache_value.expired():
+                    to_rm.append(key)
+        for key in to_rm:
+            self._remove_key(key)
+
+    def _remove_key(self, key):
+        item = self.cache[key]
+        if self.max_mem_size:
+            key_size = getsizeof(key)
+            self.current_size -= item.size + key_size
+
+        del self.cache[key]
+
+    def __contains__(self, key):
+        self._check_expired(key)
+        return key in self.cache
+
+    def refresh_key_ttl(self, key: Any, milliseconds=None):
+        """Do refresh of key ttl, if present."""
+        cache_value = self.cache.get(key)
+        if cache_value and (milliseconds or self.timeout):
+            ms = milliseconds if milliseconds else self.timeout
+            expire_at = utcnow() + timedelta(milliseconds=ms)
+            cache_value.refresh_ttl(expire_at)
+
+    @classmethod
+    def get_key(cls, *args, **kwargs):
+        """Helper method to generate keys from *args, **kwargs."""
+        sorted_kwargs = sorted(kwargs.items(), key=lambda item: item[0])
+        kwargs_list = [f"{key}={cls.serialize_key(val)}" for key, val in sorted_kwargs]
+        items = list(args) + kwargs_list
+        return "-".join([cls.serialize_key(item) for item in items])
+
+    @classmethod
+    def serialize_key(cls, data: Any):
+        if isinstance(data, dict):
+            return ",".join(
+                [f"{key}={cls.serialize_key(val)}" for key, val in data.items()]
+            )
+        elif isinstance(data, list):
+            return ",".join([cls.serialize_key(val) for val in data])
+        elif isinstance(data, str):
+            return data
+        else:
+            return str(data)
+
+    def expire(self, *args, **kwargs):
+        """Usefull to expire any combination of *args, **kwargs."""
+        key = self.get_key(*args, **kwargs)
+        if key in self.cache:
+            self._remove_key(key)
+
+    @contextmanager
+    def _scoped(self):
+        if self.lock:
+            with self.lock:
+                yield
+        else:
+            yield
+
+
+class LRUCache(ExpirableCache):
+    def get(self, key):
+        cache_value = super().get(key, fetch_value=False)
+        if cache_value:
+            with self._scoped():
+                self._increment(cache_value)
+            return cache_value.value
+
+        return None
+
+    def _increment(self, val: CacheValue):
+        val.increment()
+
+    def _pop_one(self):
+        ordered_cache = sorted(self.cache.items(), key=lambda item: item[1].access)
+        key, _ = ordered_cache[0]
+        self._remove_key(key)
+
+    @property
+    def access(self):
+        """Get accesses as map."""
+        return {key: val.access for key, val in self.cache.items()}
+
+
+# Decorator!
+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
+
+    def __call__(self, func):
+        def wrapper(*args, **kwargs):
+            key = "any" if self.skip_args else self.cache.get_key(*args, **kwargs)
+
+            if key not in self.cache:
+                resp = func(*args, **kwargs)
+                self.cache.set(key, resp)
+                return resp
+            else:
+                return self.cache.get(key)
+
+        wrapper.cache = self.cache
+
+        return wrapper
+
+
+class AsyncCacheDecorator(CacheDecorator):
+    """Async Decorator for ExpirableCache"""
+
+    def __call__(self, func):
+        async def async_wrapper(*args, **kwargs):
+            key = "any" if self.skip_args else self.cache.get_key(*args, **kwargs)
+
+            if key not in self.cache:
+                resp = await func(*args, **kwargs)
+                self.cache.set(key, resp)
+                return resp
+            else:
+                return self.cache.get(key)
+
+        async_wrapper.cache = self.cache
+
+        return async_wrapper

onecache/cache_value.py

@@ -0,0 +1,34 @@
+from datetime import datetime
+from sys import getsizeof
+from typing import Any, Optional
+
+from onecache.utils import IS_PYPY, utcnow
+
+
+class CacheValue:
+    """Dummy class for handling cache values."""
+
+    def __init__(self, value: Any, expire_at: Optional[datetime] = None):
+        self.size = None if IS_PYPY else getsizeof(value)
+        self.access = 0
+
+        self.value = value
+        self.expire_at = expire_at
+
+    def set_expired(self, data):
+        self.expire_at = data
+
+    def expired(self):
+        """Check if value is expired."""
+        if self.expire_at:
+            return utcnow() > self.expire_at
+        return False  # pragma: no cover
+
+    def refresh_ttl(self, expire_at: datetime):
+        self.expire_at = expire_at
+
+    def increment(self):
+        self.access += 1
+
+    def __eq__(self, otherinstance: "CacheValue"):
+        return self.value == otherinstance.value

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.7.0.dist-info/METADATA

@@ -0,0 +1,102 @@
+Metadata-Version: 2.1
+Name: onecache
+Version: 0.7.0
+Summary: Python cache for sync and async code
+License: MIT
+Author: Johanderson Mogollon
+Author-email: johander1822@gmail.com
+Requires-Python: >=3.8,<3.13
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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 :: Implementation :: PyPy
+Description-Content-Type: text/markdown
+
+
+[![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 LRU algoritm. Cache can optionally have TTL.
+
+Tested in python 3.7, 3.9, 3.11 and pypy3.9 for windows, mac and linux (see github status badge), it should work in versions between them. It may work for python3.6
+
+# 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. Ceil for sum of cache values 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 oldest.
+
+
+# Development
+
+Install packages with pip-tools:
+```bash
+pip install pip-tools
+pip-compile
+pip-compile test-requirements.in
+pip-sync requirements.txt test-requirements.txt
+```
+
+# Contribute
+
+1. Fork
+2. create a branch `feature/your_feature`
+3. commit - push - pull request
+
+Thanks :)
+

onecache-0.7.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+onecache/__init__.py,sha256=jwfOOuz_wmy9f1iXhIh4XZB4T-602qJOW3ny8TYXTqc,8148
+onecache/cache_value.py,sha256=6IRKg_Pj6kYHcTJMqD0ua9FTs5LBMK0J2XUQogNlk8Q,900
+onecache/utils.py,sha256=E8Sv5-QSS_gdnaFXIN4dIlR4FUqKKURJ64SkhPinVdU,268
+onecache-0.7.0.dist-info/METADATA,sha256=Soyi6rNUTsccCJ_ZCclggCBSASsPTcLYxLw9AyaqY5k,3268
+onecache-0.7.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+onecache-0.7.0.dist-info/RECORD,,

onecache-0.7.0.dist-info/WHEEL

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