cachier 3.2.1__py3-none-any.whl → 3.4.0__py3-none-any.whl

cachier/_types.py

@@ -1,9 +1,11 @@
-from typing import TYPE_CHECKING, Callable, Literal
+from typing import TYPE_CHECKING, Callable, Literal, Union
 
 if TYPE_CHECKING:
     import pymongo.collection
+    import redis
 
 
 HashFunc = Callable[..., str]
 Mongetter = Callable[[], "pymongo.collection.Collection"]
-Backend = Literal["pickle", "mongo", "memory"]
+RedisClient = Union["redis.Redis", Callable[[], "redis.Redis"]]
+Backend = Literal["pickle", "mongo", "memory", "redis"]

cachier/core.py

@@ -17,6 +17,7 @@ from functools import wraps
 from typing import Any, Callable, Optional, Union
 from warnings import warn
 
+from ._types import RedisClient
 from .config import (
     Backend,
     HashFunc,
@@ -27,10 +28,12 @@ from .cores.base import RecalculationNeeded, _BaseCore
 from .cores.memory import _MemoryCore
 from .cores.mongo import _MongoCore
 from .cores.pickle import _PickleCore
+from .cores.redis import _RedisCore
 from .cores.sql import _SQLCore
 
 MAX_WORKERS_ENVAR_NAME = "CACHIER_MAX_WORKERS"
 DEFAULT_MAX_WORKERS = 8
+ZERO_TIMEDELTA = timedelta(seconds=0)
 
 
 def _max_workers():
@@ -109,6 +112,7 @@ def cachier(
     backend: Optional[Backend] = None,
     mongetter: Optional[Mongetter] = None,
     sql_engine: Optional[Union[str, Any, Callable[[], Any]]] = None,
+    redis_client: Optional["RedisClient"] = None,
     stale_after: Optional[timedelta] = None,
     next_time: Optional[bool] = None,
     cache_dir: Optional[Union[str, os.PathLike]] = None,
@@ -136,9 +140,9 @@ def cachier(
     hash_params : callable, optional
     backend : str, optional
         The name of the backend to use. Valid options currently include
-        'pickle', 'mongo', 'memory', and 'sql'. If not provided, defaults to
-        'pickle' unless the 'mongetter' argument is passed, in which
-        case the mongo backend is automatically selected.
+        'pickle', 'mongo', 'memory', 'sql', and 'redis'. If not provided,
+        defaults to 'pickle', unless a core-associated parameter is provided
+
     mongetter : callable, optional
         A callable that takes no arguments and returns a pymongo.Collection
         object with writing permissions. If unset a local pickle cache is used
@@ -146,6 +150,9 @@ def cachier(
     sql_engine : str, Engine, or callable, optional
         SQLAlchemy connection string, Engine, or callable returning an Engine.
         Used for the SQL backend.
+    redis_client : redis.Redis or callable, optional
+        Redis client instance or callable returning a Redis client.
+        Used for the Redis backend.
     stale_after : datetime.timedelta, optional
         The time delta after which a cached result is considered stale. Calls
         made after the result goes stale will trigger a recalculation of the
@@ -219,14 +226,43 @@ def cachier(
             sql_engine=sql_engine,
             wait_for_calc_timeout=wait_for_calc_timeout,
         )
+    elif backend == "redis":
+        core = _RedisCore(
+            hash_func=hash_func,
+            redis_client=redis_client,
+            wait_for_calc_timeout=wait_for_calc_timeout,
+        )
     else:
         raise ValueError("specified an invalid core: %s" % backend)
 
     def _cachier_decorator(func):
         core.set_func(func)
 
-        @wraps(func)
-        def func_wrapper(*args, **kwds):
+        # ---
+        # MAINTAINER NOTE: max_age parameter
+        #
+        # The _call function below supports a per-call 'max_age' parameter,
+        # allowing users to specify a maximum allowed age for a cached value.
+        # If the cached value is older than 'max_age',
+        # a recalculation is triggered. This is in addition to the
+        # per-decorator 'stale_after' parameter.
+        #
+        # The effective staleness threshold is the minimum of 'stale_after'
+        # and 'max_age' (if provided).
+        # This ensures that the strictest max age requirement is enforced.
+        #
+        # The main function wrapper is a standard function that passes
+        # *args and **kwargs to _call. By default, max_age is None,
+        # so only 'stale_after' is considered unless overridden.
+        #
+        # The user-facing API exposes:
+        #   - Per-call: myfunc(..., max_age=timedelta(...))
+        #
+        # This design allows both one-off (per-call) and default
+        # (per-decorator) max age constraints.
+        # ---
+
+        def _call(*args, max_age: Optional[timedelta] = None, **kwds):
             nonlocal allow_none
             _allow_none = _update_with_defaults(allow_none, "allow_none", kwds)
             # print('Inside general wrapper for {}.'.format(func.__name__))
@@ -271,7 +307,23 @@ def cachier(
             if _allow_none or entry.value is not None:
                 _print("Cached result found.")
                 now = datetime.now()
-                if now - entry.time <= _stale_after:
+                max_allowed_age = _stale_after
+                nonneg_max_age = True
+                if max_age is not None:
+                    if max_age < ZERO_TIMEDELTA:
+                        _print(
+                            "max_age is negative. "
+                            "Cached result considered stale."
+                        )
+                        nonneg_max_age = False
+                    else:
+                        max_allowed_age = (
+                            min(_stale_after, max_age)
+                            if max_age is not None
+                            else _stale_after
+                        )
+                # note: if max_age < 0, we always consider a value stale
+                if nonneg_max_age and (now - entry.time <= max_allowed_age):
                     _print("And it is fresh!")
                     return entry.value
                 _print("But it is stale... :(")
@@ -305,6 +357,14 @@ def cachier(
             _print("No entry found. No current calc. Calling like a boss.")
             return _calc_entry(core, key, func, args, kwds)
 
+        # MAINTAINER NOTE: The main function wrapper is now a standard function
+        # that passes *args and **kwargs to _call. This ensures that user
+        # arguments are not shifted, and max_age is only settable via keyword
+        # argument.
+        @wraps(func)
+        def func_wrapper(*args, **kwargs):
+            return _call(*args, **kwargs)
+
         def _clear_cache():
             """Clear the cache."""
             core.clear_cache()

cachier/cores/mongo.py

@@ -77,7 +77,7 @@ class _MongoCore(_BaseCore):
             return key, None
         val = None
         if "value" in res:
-            val = pickle.loads(res["value"])  # noqa: S301
+            val = pickle.loads(res["value"])
         entry = CacheEntry(
             value=val,
             time=res.get("time", None),

cachier/cores/pickle.py

@@ -114,7 +114,7 @@ class _PickleCore(_BaseCore):
     def _load_cache_dict(self) -> Dict[str, CacheEntry]:
         try:
             with portalocker.Lock(self.cache_fpath, mode="rb") as cf:
-                cache = pickle.load(cf)  # noqa: S301
+                cache = pickle.load(cf)
             self._cache_used_fpath = str(self.cache_fpath)
         except (FileNotFoundError, EOFError):
             cache = {}
@@ -141,7 +141,7 @@ class _PickleCore(_BaseCore):
         fpath += f"_{hash_str or key}"
         try:
             with portalocker.Lock(fpath, mode="rb") as cache_file:
-                entry = pickle.load(cache_file)  # noqa: S301
+                entry = pickle.load(cache_file)
             return _PickleCore._convert_legacy_cache_entry(entry)
         except (FileNotFoundError, EOFError):
             return None

cachier/cores/redis.py

@@ -0,0 +1,225 @@
+"""A Redis-based caching core for cachier."""
+
+import pickle
+import time
+import warnings
+from datetime import datetime
+from typing import Any, Callable, Optional, Tuple, Union
+
+try:
+    import redis
+
+    REDIS_AVAILABLE = True
+except ImportError:
+    REDIS_AVAILABLE = False
+
+from .._types import HashFunc
+from ..config import CacheEntry
+from .base import RecalculationNeeded, _BaseCore, _get_func_str
+
+REDIS_SLEEP_DURATION_IN_SEC = 1
+
+
+class MissingRedisClient(ValueError):
+    """Thrown when the redis_client keyword argument is missing."""
+
+
+class _RedisCore(_BaseCore):
+    """Redis-based core for Cachier, supporting Redis backends."""
+
+    def __init__(
+        self,
+        hash_func: Optional[HashFunc],
+        redis_client: Optional[
+            Union["redis.Redis", Callable[[], "redis.Redis"]]
+        ],
+        wait_for_calc_timeout: Optional[int] = None,
+        key_prefix: str = "cachier",
+    ):
+        if not REDIS_AVAILABLE:
+            warnings.warn(
+                "`redis` was not found. Redis cores will not function. "
+                "Install with `pip install redis`.",
+                ImportWarning,
+                stacklevel=2,
+            )
+
+        super().__init__(
+            hash_func=hash_func, wait_for_calc_timeout=wait_for_calc_timeout
+        )
+        if redis_client is None:
+            raise MissingRedisClient(
+                "must specify ``redis_client`` when using the redis core"
+            )
+        self.redis_client = redis_client
+        self.key_prefix = key_prefix
+        self._func_str = None
+
+    def _resolve_redis_client(self):
+        """Resolve the Redis client from the provided parameter."""
+        if callable(self.redis_client):
+            return self.redis_client()
+        return self.redis_client
+
+    def _get_redis_key(self, key: str) -> str:
+        """Generate a Redis key for the given cache key."""
+        return f"{self.key_prefix}:{self._func_str}:{key}"
+
+    def set_func(self, func):
+        """Set the function this core will use."""
+        super().set_func(func)
+        self._func_str = _get_func_str(func)
+
+    def get_entry_by_key(self, key: str) -> Tuple[str, Optional[CacheEntry]]:
+        """Get entry based on given key from Redis."""
+        redis_client = self._resolve_redis_client()
+        redis_key = self._get_redis_key(key)
+
+        try:
+            # Get the cached data from Redis
+            cached_data = redis_client.hgetall(redis_key)
+            if not cached_data:
+                return key, None
+
+            # Deserialize the value
+            value = None
+            if cached_data.get(b"value"):
+                value = pickle.loads(cached_data[b"value"])
+
+            # Parse timestamp
+            timestamp_str = cached_data.get(b"timestamp", b"").decode("utf-8")
+            timestamp = (
+                datetime.fromisoformat(timestamp_str)
+                if timestamp_str
+                else datetime.now()
+            )
+
+            # Parse boolean fields
+            stale = (
+                cached_data.get(b"stale", b"false").decode("utf-8").lower()
+                == "true"
+            )
+            processing = (
+                cached_data.get(b"processing", b"false")
+                .decode("utf-8")
+                .lower()
+                == "true"
+            )
+            completed = (
+                cached_data.get(b"completed", b"false").decode("utf-8").lower()
+                == "true"
+            )
+
+            entry = CacheEntry(
+                value=value,
+                time=timestamp,
+                stale=stale,
+                _processing=processing,
+                _completed=completed,
+            )
+            return key, entry
+        except Exception as e:
+            warnings.warn(f"Redis get_entry_by_key failed: {e}", stacklevel=2)
+            return key, None
+
+    def set_entry(self, key: str, func_res: Any) -> None:
+        """Map the given result to the given key in Redis."""
+        redis_client = self._resolve_redis_client()
+        redis_key = self._get_redis_key(key)
+
+        try:
+            # Serialize the value
+            value_bytes = pickle.dumps(func_res)
+            now = datetime.now()
+
+            # Store in Redis using hash
+            redis_client.hset(
+                redis_key,
+                mapping={
+                    "value": value_bytes,
+                    "timestamp": now.isoformat(),
+                    "stale": "false",
+                    "processing": "false",
+                    "completed": "true",
+                },
+            )
+        except Exception as e:
+            warnings.warn(f"Redis set_entry failed: {e}", stacklevel=2)
+
+    def mark_entry_being_calculated(self, key: str) -> None:
+        """Mark the entry mapped by the given key as being calculated."""
+        redis_client = self._resolve_redis_client()
+        redis_key = self._get_redis_key(key)
+
+        try:
+            now = datetime.now()
+            redis_client.hset(
+                redis_key,
+                mapping={
+                    "timestamp": now.isoformat(),
+                    "stale": "false",
+                    "processing": "true",
+                    "completed": "false",
+                },
+            )
+        except Exception as e:
+            warnings.warn(
+                f"Redis mark_entry_being_calculated failed: {e}", stacklevel=2
+            )
+
+    def mark_entry_not_calculated(self, key: str) -> None:
+        """Mark the entry mapped by the given key as not being calculated."""
+        redis_client = self._resolve_redis_client()
+        redis_key = self._get_redis_key(key)
+
+        try:
+            redis_client.hset(redis_key, "processing", "false")
+        except Exception as e:
+            warnings.warn(
+                f"Redis mark_entry_not_calculated failed: {e}", stacklevel=2
+            )
+
+    def wait_on_entry_calc(self, key: str) -> Any:
+        """Wait on the entry with keys being calculated and returns result."""
+        time_spent = 0
+        while True:
+            time.sleep(REDIS_SLEEP_DURATION_IN_SEC)
+            time_spent += REDIS_SLEEP_DURATION_IN_SEC
+            key, entry = self.get_entry_by_key(key)
+            if entry is None:
+                raise RecalculationNeeded()
+            if not entry._processing:
+                return entry.value
+            self.check_calc_timeout(time_spent)
+
+    def clear_cache(self) -> None:
+        """Clear the cache of this core."""
+        redis_client = self._resolve_redis_client()
+        pattern = f"{self.key_prefix}:{self._func_str}:*"
+
+        try:
+            # Find all keys matching the pattern
+            keys = redis_client.keys(pattern)
+            if keys:
+                redis_client.delete(*keys)
+        except Exception as e:
+            warnings.warn(f"Redis clear_cache failed: {e}", stacklevel=2)
+
+    def clear_being_calculated(self) -> None:
+        """Mark all entries in this cache as not being calculated."""
+        redis_client = self._resolve_redis_client()
+        pattern = f"{self.key_prefix}:{self._func_str}:*"
+
+        try:
+            # Find all keys matching the pattern
+            keys = redis_client.keys(pattern)
+            if keys:
+                # Use pipeline for efficiency
+                pipe = redis_client.pipeline()
+                for key in keys:
+                    pipe.hset(key, "processing", "false")
+                pipe.execute()
+        except Exception as e:
+            warnings.warn(
+                f"Redis clear_being_calculated failed: {e}", stacklevel=2
+            )

cachier/version.info

@@ -1 +1 @@
-3.2.1
+3.4.0

{cachier-3.2.1.dist-info → cachier-3.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cachier
-Version: 3.2.1
+Version: 3.4.0
 Summary: Persistent, stale-free, local and cross-machine caching for Python functions.
 Author-email: Shay Palachy Affek <shay.palachy@gmail.com>
 License: MIT License
@@ -99,7 +99,9 @@ Features
 * Defining "shelf life" for cached values.
 * Local caching using pickle files.
 * Cross-machine caching using MongoDB.
+* Redis-based caching for high-performance scenarios.
 * Thread-safety.
+* **Per-call max age:** Specify a maximum age for cached values per call.
 
 Cachier is **NOT**:
 
@@ -282,6 +284,27 @@ Per-function call arguments
 
 Cachier also accepts several keyword arguments in the calls of the function it wraps rather than in the decorator call, allowing you to modify its behaviour for a specific function call.
 
+**Max Age (max_age)**
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+You can specify a maximum allowed age for a cached value on a per-call basis using the `max_age` keyword argument. If the cached value is older than this threshold, a recalculation is triggered. This is in addition to the `stale_after` parameter set at the decorator level; the strictest (smallest) threshold is enforced.
+
+.. code-block:: python
+
+  from datetime import timedelta
+  from cachier import cachier
+
+  @cachier(stale_after=timedelta(days=3))
+  def add(a, b):
+      return a + b
+
+  # Use a per-call max age:
+  result = add(1, 2, max_age=timedelta(seconds=10))  # Only use cache if value is <10s old
+
+**How it works:**
+- The effective max age threshold is the minimum of `stale_after` (from the decorator) and `max_age` (from the call).
+- If the cached value is older than this threshold, a new calculation is triggered and the cache is updated.
+- If not, the cached value is returned as usual.
+
 Ignore Cache
 ~~~~~~~~~~~~
 
@@ -426,6 +449,56 @@ Cachier supports a generic SQL backend via SQLAlchemy, allowing you to use SQLit
     def my_func(x):
         return x * 2
 
+Redis Core
+----------
+
+**Note:** The Redis core requires the redis package to be installed. It is not installed by default with cachier. To use the Redis backend, run::
+
+    pip install redis
+
+Cachier supports Redis-based caching for high-performance scenarios. Redis provides fast in-memory storage with optional persistence.
+
+**Usage Example (Local Redis):**
+
+.. code-block:: python
+
+    import redis
+    from cachier import cachier
+
+    # Create Redis client
+    redis_client = redis.Redis(host='localhost', port=6379, db=0)
+
+    @cachier(backend="redis", redis_client=redis_client)
+    def my_func(x):
+        return x * 2
+
+**Usage Example (Redis with custom key prefix):**
+
+.. code-block:: python
+
+    import redis
+    from cachier import cachier
+
+    redis_client = redis.Redis(host='localhost', port=6379, db=0)
+
+    @cachier(backend="redis", redis_client=redis_client, key_prefix="myapp")
+    def my_func(x):
+        return x * 2
+
+**Usage Example (Redis with callable client):**
+
+.. code-block:: python
+
+    import redis
+    from cachier import cachier
+
+    def get_redis_client():
+        return redis.Redis(host='localhost', port=6379, db=0)
+
+    @cachier(backend="redis", redis_client=get_redis_client)
+    def my_func(x):
+        return x * 2
+
 **Configuration Options:**
 
 - ``sql_engine``: SQLAlchemy connection string, Engine, or callable returning an Engine.

cachier-3.4.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+cachier/__init__.py,sha256=1isxXaP2l6Vq7gC1Gob6hduRLC07dHfWze1-oCjwSP0,415
+cachier/__main__.py,sha256=upg-TlHs1vngKYvkjoPpl3Pvl6xOx4ut-M1mElMiAo0,443
+cachier/_types.py,sha256=u-1NWfZqcvwLa5qDmiTxIN4btM6NiWta212u8yPo02o,335
+cachier/_version.py,sha256=jnPPRn_qmjNi-qmQjlHnzNGf3LSBTYkMmJdGjxMTOBM,1089
+cachier/config.py,sha256=6hyQtn9T6UXu2UQhKJltWT0Nu4OBS4ION1x7Lt1i8Og,3838
+cachier/core.py,sha256=W1O_a9rkgsErG3spVPZpnfRu9k0MbV94rGkv79KDgBA,16243
+cachier/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cachier/version.info,sha256=9ePpPlj_wqIKPKU-gCW8UNfB3MvvSzTiOIqpu_hnhGY,6
+cachier/cores/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cachier/cores/base.py,sha256=s7qgmDJA4LGub6ydGfMk9vVJW4fgeU0EXl-9gmpuh28,3683
+cachier/cores/memory.py,sha256=fsvqq9rwwmAaMBvYo-oUNAxB6UOyfBpuf8ACW_XTaU0,3572
+cachier/cores/mongo.py,sha256=wVit36jQeNkP1KyxMtm6jDglazpdORYzTOPJ0q10BWI,4979
+cachier/cores/pickle.py,sha256=FuEl2i_U4Q3k9JUs4ylJqM3n7BVY6cXEqKmdW56AEDg,10650
+cachier/cores/redis.py,sha256=rWrkEwWPzfFvH1eLkgBdhzxqPtJtx6N_sYcqRPy_P9Y,7553
+cachier/cores/sql.py,sha256=nuf2-Szo7VTPRa7IC3JGWEtGsBtdkIrx0bhOm3U0mfE,9895
+cachier-3.4.0.dist-info/licenses/LICENSE,sha256=-2WrMJkIa0gVP6YQHXXDT7ws-S3M2NEVEF4XF3K8qrY,1069
+cachier-3.4.0.dist-info/METADATA,sha256=V409D2EKlPVNAEf_uAzJDIJCQQJjzyoE_g1FnjaSnzs,24446
+cachier-3.4.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+cachier-3.4.0.dist-info/entry_points.txt,sha256=x4Y7t6Y0Qev_3fgG-Jv7TrsvVdJty3FnGAdkT8-_5mY,49
+cachier-3.4.0.dist-info/top_level.txt,sha256=_rW_HiJumDCch67YT-WAgzcyvKg5RiYDMZq9d-0ZpaE,8
+cachier-3.4.0.dist-info/RECORD,,

cachier-3.2.1.dist-info/RECORD

@@ -1,20 +0,0 @@
-cachier/__init__.py,sha256=1isxXaP2l6Vq7gC1Gob6hduRLC07dHfWze1-oCjwSP0,415
-cachier/__main__.py,sha256=upg-TlHs1vngKYvkjoPpl3Pvl6xOx4ut-M1mElMiAo0,443
-cachier/_types.py,sha256=EGJMiw-oCIC_cDLyzw7YC40lfo8jnD3zMmoJpA9Y8Iw,238
-cachier/_version.py,sha256=jnPPRn_qmjNi-qmQjlHnzNGf3LSBTYkMmJdGjxMTOBM,1089
-cachier/config.py,sha256=6hyQtn9T6UXu2UQhKJltWT0Nu4OBS4ION1x7Lt1i8Og,3838
-cachier/core.py,sha256=7pqf_EGvGXu5WWtC5MeY0tVW4M59XljZI9_2R4RVfRU,13627
-cachier/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-cachier/version.info,sha256=OCJyh4MEn8LyKlbR7nTWI1LEn7-BxrVLUIMNb2HDryI,6
-cachier/cores/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-cachier/cores/base.py,sha256=s7qgmDJA4LGub6ydGfMk9vVJW4fgeU0EXl-9gmpuh28,3683
-cachier/cores/memory.py,sha256=fsvqq9rwwmAaMBvYo-oUNAxB6UOyfBpuf8ACW_XTaU0,3572
-cachier/cores/mongo.py,sha256=pCBrxLsmGr68Q50JVD_CUPAYwhaLDrJUQs_6A-_GYLA,4993
-cachier/cores/pickle.py,sha256=FgfvZWAFdWQPOo3G-L57iEV2ujEkIDH8TyGzbarsZeE,10678
-cachier/cores/sql.py,sha256=nuf2-Szo7VTPRa7IC3JGWEtGsBtdkIrx0bhOm3U0mfE,9895
-cachier-3.2.1.dist-info/licenses/LICENSE,sha256=-2WrMJkIa0gVP6YQHXXDT7ws-S3M2NEVEF4XF3K8qrY,1069
-cachier-3.2.1.dist-info/METADATA,sha256=xowxZuYhc4r5f4pKxrhROtHGT7FYObRJ4ULWFDXwA-Q,22101
-cachier-3.2.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-cachier-3.2.1.dist-info/entry_points.txt,sha256=x4Y7t6Y0Qev_3fgG-Jv7TrsvVdJty3FnGAdkT8-_5mY,49
-cachier-3.2.1.dist-info/top_level.txt,sha256=_rW_HiJumDCch67YT-WAgzcyvKg5RiYDMZq9d-0ZpaE,8
-cachier-3.2.1.dist-info/RECORD,,