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

cachier/core.py

@@ -31,6 +31,7 @@ from .cores.sql import _SQLCore
 
 MAX_WORKERS_ENVAR_NAME = "CACHIER_MAX_WORKERS"
 DEFAULT_MAX_WORKERS = 8
+ZERO_TIMEDELTA = timedelta(seconds=0)
 
 
 def _max_workers():
@@ -225,8 +226,31 @@ def cachier(
     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 +295,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 +345,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/version.info

@@ -1 +1 @@
-3.2.1
+3.3.0

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cachier
-Version: 3.2.1
+Version: 3.3.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
@@ -100,6 +100,7 @@ Features
 * Local caching using pickle files.
 * Cross-machine caching using MongoDB.
 * Thread-safety.
+* **Per-call max age:** Specify a maximum age for cached values per call.
 
 Cachier is **NOT**:
 
@@ -282,6 +283,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
 ~~~~~~~~~~~~
 

{cachier-3.2.1.dist-info → cachier-3.3.0.dist-info}/RECORD

@@ -3,18 +3,18 @@ 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/core.py,sha256=PHLDA6Mabih-mi4y3CBsb8_vBIpvYQt547_Y57fo8uI,15825
 cachier/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-cachier/version.info,sha256=OCJyh4MEn8LyKlbR7nTWI1LEn7-BxrVLUIMNb2HDryI,6
+cachier/version.info,sha256=Xu5sDFxpAfXlI_CkNLykEG4f9xNt60UfmCsLsaexNxY,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,,
+cachier-3.3.0.dist-info/licenses/LICENSE,sha256=-2WrMJkIa0gVP6YQHXXDT7ws-S3M2NEVEF4XF3K8qrY,1069
+cachier-3.3.0.dist-info/METADATA,sha256=P8GoF2LSZKA5Tp8NunrJvS_f1XlytO4HsCmDsUy4oxQ,23136
+cachier-3.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+cachier-3.3.0.dist-info/entry_points.txt,sha256=x4Y7t6Y0Qev_3fgG-Jv7TrsvVdJty3FnGAdkT8-_5mY,49
+cachier-3.3.0.dist-info/top_level.txt,sha256=_rW_HiJumDCch67YT-WAgzcyvKg5RiYDMZq9d-0ZpaE,8
+cachier-3.3.0.dist-info/RECORD,,