cachier 3.0.0__py3-none-any.whl → 3.1.0__py3-none-any.whl

cachier/__init__.py

@@ -2,15 +2,15 @@ from ._version import *  # noqa: F403
 from .config import (
     disable_caching,
     enable_caching,
-    get_default_params,
-    set_default_params,
+    get_global_params,
+    set_global_params,
 )
 from .core import cachier
 
 __all__ = [
     "cachier",
-    "set_default_params",
-    "get_default_params",
+    "set_global_params",
+    "get_global_params",
     "enable_caching",
     "disable_caching",
 ]

cachier/__main__.py

@@ -7,7 +7,7 @@ from cachier.core import _set_max_workers
 
 @click.group()
 def cli():
-    """A command-line interface for cachier."""
+    """A command-line interface for cachier."""  # noqa: D401
 
 
 @cli.command("Limits the number of worker threads used by cachier.")

cachier/config.py

@@ -2,7 +2,10 @@ import datetime
 import hashlib
 import os
 import pickle
-from typing import Optional, TypedDict, Union
+import threading
+from collections.abc import Mapping
+from dataclasses import dataclass, replace
+from typing import Any, Optional, Union
 
 from ._types import Backend, HashFunc, Mongetter
 
@@ -16,33 +19,36 @@ def _default_hash_func(args, kwds):
     return hashlib.sha256(serialized).hexdigest()
 
 
-class Params(TypedDict):
-    caching_enabled: bool
-    hash_func: HashFunc
-    backend: Backend
-    mongetter: Optional[Mongetter]
-    stale_after: datetime.timedelta
-    next_time: bool
-    cache_dir: Union[str, os.PathLike]
-    pickle_reload: bool
-    separate_files: bool
-    wait_for_calc_timeout: int
-    allow_none: bool
-
-
-_default_params: Params = {
-    "caching_enabled": True,
-    "hash_func": _default_hash_func,
-    "backend": "pickle",
-    "mongetter": None,
-    "stale_after": datetime.timedelta.max,
-    "next_time": False,
-    "cache_dir": "~/.cachier/",
-    "pickle_reload": True,
-    "separate_files": False,
-    "wait_for_calc_timeout": 0,
-    "allow_none": False,
-}
+@dataclass
+class Params:
+    """Default definition for cachier parameters."""
+
+    caching_enabled: bool = True
+    hash_func: HashFunc = _default_hash_func
+    backend: Backend = "pickle"
+    mongetter: Optional[Mongetter] = None
+    stale_after: datetime.timedelta = datetime.timedelta.max
+    next_time: bool = False
+    cache_dir: Union[str, os.PathLike] = "~/.cachier/"
+    pickle_reload: bool = True
+    separate_files: bool = False
+    wait_for_calc_timeout: int = 0
+    allow_none: bool = False
+
+
+_global_params = Params()
+
+
+@dataclass
+class CacheEntry:
+    """Data class for cache entries."""
+
+    value: Any
+    time: datetime
+    stale: bool
+    _processing: bool
+    _condition: Optional[threading.Condition] = None
+    _completed: bool = False
 
 
 def _update_with_defaults(
@@ -55,11 +61,25 @@ def _update_with_defaults(
         if kw_name in func_kwargs:
             return func_kwargs.pop(kw_name)
     if param is None:
-        return cachier.config._default_params[name]
+        return getattr(cachier.config._global_params, name)
     return param
 
 
-def set_default_params(**params):
+def set_default_params(**params: Mapping) -> None:
+    """Configure default parameters applicable to all memoized functions."""
+    # It is kept for backwards compatibility with desperation warning
+    import warnings
+
+    warnings.warn(
+        "Called `set_default_params` is deprecated and will be removed."
+        " Please use `set_global_params` instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    set_global_params(**params)
+
+
+def set_global_params(**params: Mapping) -> None:
     """Configure global parameters applicable to all memoized functions.
 
     This function takes the same keyword parameters as the ones defined in the
@@ -74,28 +94,46 @@ def set_default_params(**params):
     """
     import cachier
 
-    valid_params = (
-        p for p in params.items() if p[0] in cachier.config._default_params
+    valid_params = {
+        k: v
+        for k, v in params.items()
+        if hasattr(cachier.config._global_params, k)
+    }
+    cachier.config._global_params = replace(
+        cachier.config._global_params, **valid_params
+    )
+
+
+def get_default_params() -> Params:
+    """Get current set of default parameters."""
+    # It is kept for backwards compatibility with desperation warning
+    import warnings
+
+    warnings.warn(
+        "Called `get_default_params` is deprecated and will be removed."
+        " Please use `get_global_params` instead.",
+        DeprecationWarning,
+        stacklevel=2,
     )
-    _default_params.update(valid_params)
+    return get_global_params()
 
 
-def get_default_params():
+def get_global_params() -> Params:
     """Get current set of default parameters."""
     import cachier
 
-    return cachier.config._default_params
+    return cachier.config._global_params
 
 
 def enable_caching():
     """Enable caching globally."""
     import cachier
 
-    cachier.config._default_params["caching_enabled"] = True
+    cachier.config._global_params.caching_enabled = True
 
 
 def disable_caching():
     """Disable caching globally."""
     import cachier
 
-    cachier.config._default_params["caching_enabled"] = False
+    cachier.config._global_params.caching_enabled = False

cachier/core.py

@@ -14,14 +14,13 @@ import warnings
 from collections import OrderedDict
 from concurrent.futures import ThreadPoolExecutor
 from functools import wraps
-from typing import Optional, Union
+from typing import Any, Optional, Union
 from warnings import warn
 
 from .config import (
     Backend,
     HashFunc,
     Mongetter,
-    _default_params,
     _update_with_defaults,
 )
 from .cores.base import RecalculationNeeded, _BaseCore
@@ -56,13 +55,11 @@ def _function_thread(core, key, func, args, kwds):
         print(f"Function call failed with the following exception:\n{exc}")
 
 
-def _calc_entry(core, key, func, args, kwds):
+def _calc_entry(core, key, func, args, kwds) -> Optional[Any]:
+    core.mark_entry_being_calculated(key)
     try:
-        core.mark_entry_being_calculated(key)
-        # _get_executor().submit(core.mark_entry_being_calculated, key)
         func_res = func(*args, **kwds)
         core.set_entry(key, func_res)
-        # _get_executor().submit(core.set_entry, key, func_res)
         return func_res
     finally:
         core.mark_entry_not_calculated(key)
@@ -118,7 +115,7 @@ def cachier(
     wait_for_calc_timeout: Optional[int] = None,
     allow_none: Optional[bool] = None,
 ):
-    """A persistent, stale-free memoization decorator.
+    """Wrap as a persistent, stale-free memoization decorator.
 
     The positional and keyword arguments to the wrapped function must be
     hashable (i.e. Python's immutable built-in objects, not mutable
@@ -127,13 +124,14 @@ def cachier(
     value is their id), equal objects across different sessions will not yield
     identical keys.
 
-    Arguments
+    Arguments:
     ---------
     hash_func : callable, optional
         A callable that gets the args and kwargs from the decorated function
         and returns a hash key for them. This parameter can be used to enable
         the use of cachier with functions that get arguments that are not
         automatically hashable by Python.
+    hash_params : callable, optional
     backend : str, optional
         The name of the backend to use. Valid options currently include
         'pickle', 'mongo' and 'memory'. If not provided, defaults to
@@ -175,6 +173,8 @@ def cachier(
         None will not be cached and are recalculated every call.
 
     """
+    from .config import _global_params
+
     # Check for deprecated parameters
     if hash_params is not None:
         message = (
@@ -240,29 +240,34 @@ def cachier(
                 func, _is_method=core.func_is_method, args=args, kwds=kwds
             )
 
-            _print = lambda x: None  # noqa: E731
-            if verbose:
-                _print = print
-            if ignore_cache or not _default_params["caching_enabled"]:
-                return func(**kwargs)
-            key, entry = core.get_entry(tuple(), kwargs)
+            _print = print if verbose else lambda x: None
+
+            if ignore_cache or not _global_params.caching_enabled:
+                return (
+                    func(args[0], **kwargs)
+                    if core.func_is_method
+                    else func(**kwargs)
+                )
+            key, entry = core.get_entry((), kwargs)
             if overwrite_cache:
                 return _calc_entry(core, key, func, args, kwds)
-            if entry is None:
+            if entry is None or (
+                not entry._completed and not entry._processing
+            ):
                 _print("No entry found. No current calc. Calling like a boss.")
                 return _calc_entry(core, key, func, args, kwds)
             _print("Entry found.")
-            if _allow_none or entry.get("value", None) is not None:
+            if _allow_none or entry.value is not None:
                 _print("Cached result found.")
                 now = datetime.datetime.now()
-                if now - entry["time"] <= _stale_after:
+                if now - entry.time <= _stale_after:
                     _print("And it is fresh!")
-                    return entry["value"]
+                    return entry.value
                 _print("But it is stale... :(")
-                if entry["being_calculated"]:
+                if entry._processing:
                     if _next_time:
                         _print("Returning stale.")
-                        return entry["value"]  # return stale val
+                        return entry.value  # return stale val
                     _print("Already calc. Waiting on change.")
                     try:
                         return core.wait_on_entry_calc(key)
@@ -270,17 +275,17 @@ def cachier(
                         return _calc_entry(core, key, func, args, kwds)
                 if _next_time:
                     _print("Async calc and return stale")
+                    core.mark_entry_being_calculated(key)
                     try:
-                        core.mark_entry_being_calculated(key)
                         _get_executor().submit(
                             _function_thread, core, key, func, args, kwds
                         )
                     finally:
                         core.mark_entry_not_calculated(key)
-                    return entry["value"]
+                    return entry.value
                 _print("Calling decorated function and waiting")
                 return _calc_entry(core, key, func, args, kwds)
-            if entry["being_calculated"]:
+            if entry._processing:
                 _print("No value but being calculated. Waiting.")
                 try:
                     return core.wait_on_entry_calc(key)
@@ -294,17 +299,17 @@ def cachier(
             core.clear_cache()
 
         def _clear_being_calculated():
-            """Marks all entries in this cache as not being calculated."""
+            """Mark all entries in this cache as not being calculated."""
             core.clear_being_calculated()
 
         def _cache_dpath():
-            """Returns the path to the cache dir, if exists; None if not."""
+            """Return the path to the cache dir, if exists; None if not."""
             return getattr(core, "cache_dir", None)
 
-        def _precache_value(*args, value_to_cache, **kwds):
+        def _precache_value(*args, value_to_cache, **kwds):  # noqa: D417
             """Add an initial value to the cache.
 
-            Arguments
+            Arguments:
             ---------
             value_to_cache : any
                 entry to be written into the cache
@@ -314,7 +319,7 @@ def cachier(
             kwargs = _convert_args_kwargs(
                 func, _is_method=core.func_is_method, args=args, kwds=kwds
             )
-            return core.precache_value(tuple(), kwargs, value_to_cache)
+            return core.precache_value((), kwargs, value_to_cache)
 
         func_wrapper.clear_cache = _clear_cache
         func_wrapper.clear_being_calculated = _clear_being_calculated

cachier/cores/base.py

@@ -9,13 +9,15 @@
 import abc  # for the _BaseCore abstract base class
 import inspect
 import threading
-from typing import Callable
+from typing import Callable, Optional, Tuple
 
 from .._types import HashFunc
-from ..config import _update_with_defaults
+from ..config import CacheEntry, _update_with_defaults
 
 
 class RecalculationNeeded(Exception):
+    """Exception raised when a recalculation is needed."""
+
     pass
 
 
@@ -32,7 +34,7 @@ class _BaseCore:
         self.lock = threading.RLock()
 
     def set_func(self, func):
-        """Sets the function this core will use.
+        """Set the function this core will use.
 
         This has to be set before any method is called. Also determine if the
         function is an object method.
@@ -46,17 +48,21 @@ class _BaseCore:
         self.func = func
 
     def get_key(self, args, kwds):
-        """Returns a unique key based on the arguments provided."""
+        """Return a unique key based on the arguments provided."""
         return self.hash_func(args, kwds)
 
-    def get_entry(self, args, kwds):
-        """Returns the result mapped to the given arguments in this core's
-        cache, if such a mapping exists."""
+    def get_entry(self, args, kwds) -> Tuple[str, Optional[CacheEntry]]:
+        """Get entry based on given arguments.
+
+        Return the result mapped to the given arguments in this core's cache,
+        if such a mapping exists.
+
+        """
         key = self.get_key(args, kwds)
         return self.get_entry_by_key(key)
 
     def precache_value(self, args, kwds, value_to_cache):
-        """Writes a precomputed value into the cache."""
+        """Write a precomputed value into the cache."""
         key = self.get_key(args, kwds)
         self.set_entry(key, value_to_cache)
         return value_to_cache
@@ -70,31 +76,34 @@ class _BaseCore:
             raise RecalculationNeeded()
 
     @abc.abstractmethod
-    def get_entry_by_key(self, key):
-        """Returns the result mapped to the given key in this core's cache, if
-        such a mapping exists."""
+    def get_entry_by_key(self, key: str) -> Tuple[str, Optional[CacheEntry]]:
+        """Get entry based on given key.
+
+        Return the result mapped to the given key in this core's cache, if such
+        a mapping exists.
+
+        """
 
     @abc.abstractmethod
-    def set_entry(self, key, func_res):
-        """Maps the given result to the given key in this core's cache."""
+    def set_entry(self, key: str, func_res):
+        """Map the given result to the given key in this core's cache."""
 
     @abc.abstractmethod
-    def mark_entry_being_calculated(self, key):
-        """Marks the entry mapped by the given key as being calculated."""
+    def mark_entry_being_calculated(self, key: str) -> None:
+        """Mark the entry mapped by the given key as being calculated."""
 
     @abc.abstractmethod
-    def mark_entry_not_calculated(self, key):
-        """Marks the entry mapped by the given key as not being calculated."""
+    def mark_entry_not_calculated(self, key: str) -> None:
+        """Mark the entry mapped by the given key as not being calculated."""
 
     @abc.abstractmethod
-    def wait_on_entry_calc(self, key):
-        """Waits on the entry mapped by key being calculated and returns
-        result."""
+    def wait_on_entry_calc(self, key: str) -> None:
+        """Wait on the entry with keys being calculated and returns result."""
 
     @abc.abstractmethod
-    def clear_cache(self):
-        """Clears the cache of this core."""
+    def clear_cache(self) -> None:
+        """Clear the cache of this core."""
 
     @abc.abstractmethod
-    def clear_being_calculated(self):
-        """Marks all entries in this cache as not being calculated."""
+    def clear_being_calculated(self) -> None:
+        """Mark all entries in this cache as not being calculated."""

cachier/cores/memory.py

@@ -2,8 +2,10 @@
 
 import threading
 from datetime import datetime
+from typing import Any, Optional, Tuple
 
 from .._types import HashFunc
+from ..config import CacheEntry
 from .base import _BaseCore, _get_func_str
 
 
@@ -14,76 +16,82 @@ class _MemoryCore(_BaseCore):
         super().__init__(hash_func, wait_for_calc_timeout)
         self.cache = {}
 
-    def _hash_func_key(self, key):
+    def _hash_func_key(self, key: str) -> str:
         return f"{_get_func_str(self.func)}:{key}"
 
-    def get_entry_by_key(self, key, reload=False):
+    def get_entry_by_key(
+        self, key: str, reload=False
+    ) -> Tuple[str, Optional[CacheEntry]]:
         with self.lock:
             return key, self.cache.get(self._hash_func_key(key), None)
 
-    def set_entry(self, key, func_res):
+    def set_entry(self, key: str, func_res: Any) -> None:
+        hash_key = self._hash_func_key(key)
         with self.lock:
             try:
                 # we need to retain the existing condition so that
                 # mark_entry_not_calculated can notify all possibly-waiting
                 # threads about it
-                cond = self.cache[self._hash_func_key(key)]["condition"]
+                cond = self.cache[hash_key]._condition
             except KeyError:  # pragma: no cover
                 cond = None
-            self.cache[self._hash_func_key(key)] = {
-                "value": func_res,
-                "time": datetime.now(),
-                "stale": False,
-                "being_calculated": False,
-                "condition": cond,
-            }
+            self.cache[hash_key] = CacheEntry(
+                value=func_res,
+                time=datetime.now(),
+                stale=False,
+                _processing=False,
+                _condition=cond,
+                _completed=True,
+            )
 
-    def mark_entry_being_calculated(self, key):
+    def mark_entry_being_calculated(self, key: str) -> None:
         with self.lock:
             condition = threading.Condition()
+            hash_key = self._hash_func_key(key)
+            if hash_key in self.cache:
+                self.cache[hash_key]._processing = True
+                self.cache[hash_key]._condition = condition
             # condition.acquire()
-            try:
-                self.cache[self._hash_func_key(key)]["being_calculated"] = True
-                self.cache[self._hash_func_key(key)]["condition"] = condition
-            except KeyError:
-                self.cache[self._hash_func_key(key)] = {
-                    "value": None,
-                    "time": datetime.now(),
-                    "stale": False,
-                    "being_calculated": True,
-                    "condition": condition,
-                }
+            else:
+                self.cache[hash_key] = CacheEntry(
+                    value=None,
+                    time=datetime.now(),
+                    stale=False,
+                    _processing=True,
+                    _condition=condition,
+                )
 
-    def mark_entry_not_calculated(self, key):
+    def mark_entry_not_calculated(self, key: str) -> None:
+        hash_key = self._hash_func_key(key)
         with self.lock:
-            try:
-                entry = self.cache[self._hash_func_key(key)]
-            except KeyError:  # pragma: no cover
+            if hash_key not in self.cache:
                 return  # that's ok, we don't need an entry in that case
-            entry["being_calculated"] = False
-            cond = entry["condition"]
+            entry = self.cache[hash_key]
+            entry._processing = False
+            cond = entry._condition
             if cond:
                 cond.acquire()
                 cond.notify_all()
                 cond.release()
-                entry["condition"] = None
+                entry._condition = None
 
-    def wait_on_entry_calc(self, key):
+    def wait_on_entry_calc(self, key: str) -> Any:
+        hash_key = self._hash_func_key(key)
         with self.lock:  # pragma: no cover
-            entry = self.cache[self._hash_func_key(key)]
-            if not entry["being_calculated"]:
-                return entry["value"]
-        entry["condition"].acquire()
-        entry["condition"].wait()
-        entry["condition"].release()
-        return self.cache[self._hash_func_key(key)]["value"]
+            entry = self.cache[hash_key]
+            if not entry._processing:
+                return entry.value
+        entry._condition.acquire()
+        entry._condition.wait()
+        entry._condition.release()
+        return self.cache[hash_key].value
 
-    def clear_cache(self):
+    def clear_cache(self) -> None:
         with self.lock:
             self.cache.clear()
 
-    def clear_being_calculated(self):
+    def clear_being_calculated(self) -> None:
         with self.lock:
             for entry in self.cache.values():
-                entry["being_calculated"] = False
-                entry["condition"] = None
+                entry._processing = False
+                entry._condition = None

cachier/cores/mongo.py

@@ -13,8 +13,10 @@ import time  # to sleep when waiting on Mongo cache\
 import warnings  # to warn if pymongo is missing
 from contextlib import suppress
 from datetime import datetime
+from typing import Any, Optional, Tuple
 
 from .._types import HashFunc, Mongetter
+from ..config import CacheEntry
 
 with suppress(ImportError):
     from bson.binary import Binary  # to save binary data to mongodb
@@ -41,8 +43,9 @@ class _MongoCore(_BaseCore):
     ):
         if "pymongo" not in sys.modules:
             warnings.warn(
-                "Cachier warning: pymongo was not found. "
-                "MongoDB cores will not function."
+                "`pymongo` was not found. MongoDB cores will not function.",
+                ImportWarning,
+                stacklevel=2,
             )  # pragma: no cover
 
         super().__init__(hash_func, wait_for_calc_timeout)
@@ -64,29 +67,23 @@ class _MongoCore(_BaseCore):
     def _func_str(self) -> str:
         return _get_func_str(self.func)
 
-    def get_entry_by_key(self, key):
+    def get_entry_by_key(self, key: str) -> Tuple[str, Optional[CacheEntry]]:
         res = self.mongo_collection.find_one(
             {"func": self._func_str, "key": key}
         )
         if not res:
             return key, None
-        try:
-            entry = {
-                "value": pickle.loads(res["value"]),  # noqa: S301
-                "time": res.get("time", None),
-                "stale": res.get("stale", False),
-                "being_calculated": res.get("being_calculated", False),
-            }
-        except KeyError:
-            entry = {
-                "value": None,
-                "time": res.get("time", None),
-                "stale": res.get("stale", False),
-                "being_calculated": res.get("being_calculated", False),
-            }
+        val = pickle.loads(res["value"]) if "value" in res else None  # noqa: S301
+        entry = CacheEntry(
+            value=val,
+            time=res.get("time", None),
+            stale=res.get("stale", False),
+            _processing=res.get("processing", False),
+            _completed=res.get("completed", False),
+        )
         return key, entry
 
-    def set_entry(self, key, func_res):
+    def set_entry(self, key: str, func_res: Any) -> None:
         thebytes = pickle.dumps(func_res)
         self.mongo_collection.update_one(
             filter={"func": self._func_str, "key": key},
@@ -97,31 +94,32 @@ class _MongoCore(_BaseCore):
                     "value": Binary(thebytes),
                     "time": datetime.now(),
                     "stale": False,
-                    "being_calculated": False,
+                    "processing": False,
+                    "completed": True,
                 }
             },
             upsert=True,
         )
 
-    def mark_entry_being_calculated(self, key):
+    def mark_entry_being_calculated(self, key: str) -> None:
         self.mongo_collection.update_one(
             filter={"func": self._func_str, "key": key},
-            update={"$set": {"being_calculated": True}},
+            update={"$set": {"processing": True}},
             upsert=True,
         )
 
-    def mark_entry_not_calculated(self, key):
+    def mark_entry_not_calculated(self, key: str) -> None:
         with suppress(OperationFailure):  # don't care in this case
             self.mongo_collection.update_one(
                 filter={
                     "func": self._func_str,
                     "key": key,
                 },
-                update={"$set": {"being_calculated": False}},
+                update={"$set": {"processing": False}},
                 upsert=False,  # should not insert in this case
             )
 
-    def wait_on_entry_calc(self, key):
+    def wait_on_entry_calc(self, key: str) -> Any:
         time_spent = 0
         while True:
             time.sleep(MONGO_SLEEP_DURATION_IN_SEC)
@@ -129,18 +127,18 @@ class _MongoCore(_BaseCore):
             key, entry = self.get_entry_by_key(key)
             if entry is None:
                 raise RecalculationNeeded()
-            if not entry["being_calculated"]:
-                return entry["value"]
+            if not entry._processing:
+                return entry.value
             self.check_calc_timeout(time_spent)
 
-    def clear_cache(self):
+    def clear_cache(self) -> None:
         self.mongo_collection.delete_many(filter={"func": self._func_str})
 
-    def clear_being_calculated(self):
+    def clear_being_calculated(self) -> None:
         self.mongo_collection.update_many(
             filter={
                 "func": self._func_str,
-                "being_calculated": True,
+                "processing": True,
             },
-            update={"$set": {"being_calculated": False}},
+            update={"$set": {"processing": False}},
         )

cachier/cores/pickle.py

@@ -8,15 +8,15 @@
 # Copyright (c) 2016, Shay Palachy <shaypal5@gmail.com>
 import os
 import pickle  # for local caching
-from contextlib import suppress
 from datetime import datetime
+from typing import Any, Dict, Optional, Tuple
 
 import portalocker  # to lock on pickle cache IO
 from watchdog.events import PatternMatchingEventHandler
 from watchdog.observers import Observer
 
 from .._types import HashFunc
-from ..config import _update_with_defaults
+from ..config import CacheEntry, _update_with_defaults
 
 # Alternative:  https://github.com/WoLpH/portalocker
 from .base import _BaseCore
@@ -41,32 +41,29 @@ class _PickleCore(_BaseCore):
             self.observer = None
             self.value = None
 
-        def inject_observer(self, observer):
+        def inject_observer(self, observer) -> None:
             """Inject the observer running this handler."""
             self.observer = observer
 
-        def _check_calculation(self):
-            # print('checking calc')
+        def _check_calculation(self) -> None:
             entry = self.core.get_entry_by_key(self.key, True)[1]
-            # print(self.key)
-            # print(entry)
             try:
-                if not entry["being_calculated"]:
+                if not entry._processing:
                     # print('stopping observer!')
-                    self.value = entry["value"]
+                    self.value = entry.value
                     self.observer.stop()
                 # else:
-                # print('NOT stopping observer... :(')
+                #     print('NOT stopping observer... :(')
             except TypeError:
                 self.value = None
                 self.observer.stop()
 
-        def on_created(self, event):
-            """A Watchdog Event Handler method."""
+        def on_created(self, event) -> None:
+            """A Watchdog Event Handler method."""  # noqa: D401
             self._check_calculation()  # pragma: no cover
 
-        def on_modified(self, event):
-            """A Watchdog Event Handler method."""
+        def on_modified(self, event) -> None:
+            """A Watchdog Event Handler method."""  # noqa: D401
             self._check_calculation()
 
     def __init__(
@@ -99,52 +96,54 @@ class _PickleCore(_BaseCore):
             os.path.join(os.path.realpath(self.cache_dir), self.cache_fname)
         )
 
-    def _reload_cache(self):
+    def _reload_cache(self) -> None:
         with self.lock:
             try:
-                with portalocker.Lock(
-                    self.cache_fpath, mode="rb"
-                ) as cache_file:
-                    self.cache = pickle.load(cache_file)  # noqa: S301
+                with portalocker.Lock(self.cache_fpath, mode="rb") as cf:
+                    self.cache = pickle.load(cf)  # noqa: S301
             except (FileNotFoundError, EOFError):
                 self.cache = {}
 
-    def _get_cache(self):
+    def _get_cache(self) -> Dict[str, CacheEntry]:
         with self.lock:
             if not self.cache:
                 self._reload_cache()
             return self.cache
 
-    def _get_cache_by_key(self, key=None, hash=None):
+    def _get_cache_by_key(
+        self, key=None, hash_str=None
+    ) -> Optional[Dict[str, CacheEntry]]:
         fpath = self.cache_fpath
-        fpath += f"_{key}" if hash is None else f"_{hash}"
+        fpath += f"_{hash_str or key}"
         try:
             with portalocker.Lock(fpath, mode="rb") as cache_file:
                 return pickle.load(cache_file)  # noqa: S301
         except (FileNotFoundError, EOFError):
             return None
 
-    def _clear_all_cache_files(self):
+    def _clear_all_cache_files(self) -> None:
         path, name = os.path.split(self.cache_fpath)
         for subpath in os.listdir(path):
             if subpath.startswith(f"{name}_"):
                 os.remove(os.path.join(path, subpath))
 
-    def _clear_being_calculated_all_cache_files(self):
+    def _clear_being_calculated_all_cache_files(self) -> None:
         path, name = os.path.split(self.cache_fpath)
         for subpath in os.listdir(path):
             if subpath.startswith(name):
-                entry = self._get_cache_by_key(hash=subpath.split("_")[-1])
+                entry = self._get_cache_by_key(hash_str=subpath.split("_")[-1])
                 if entry is not None:
-                    entry["being_calculated"] = False
-                    self._save_cache(entry, hash=subpath.split("_")[-1])
+                    entry.being_calculated = False
+                    self._save_cache(entry, hash_str=subpath.split("_")[-1])
 
-    def _save_cache(self, cache, key=None, hash=None):
+    def _save_cache(
+        self, cache, key: str = None, hash_str: str = None
+    ) -> None:
         fpath = self.cache_fpath
         if key is not None:
             fpath += f"_{key}"
-        elif hash is not None:
-            fpath += f"_{hash}"
+        elif hash_str is not None:
+            fpath += f"_{hash_str}"
         with self.lock:
             self.cache = cache
             with portalocker.Lock(fpath, mode="wb") as cache_file:
@@ -152,7 +151,9 @@ class _PickleCore(_BaseCore):
             if key is None:
                 self._reload_cache()
 
-    def get_entry_by_key(self, key, reload=False):
+    def get_entry_by_key(
+        self, key: str, reload: bool = False
+    ) -> Tuple[str, CacheEntry]:
         with self.lock:
             if self.separate_files:
                 return key, self._get_cache_by_key(key)
@@ -160,13 +161,14 @@ class _PickleCore(_BaseCore):
                 self._reload_cache()
             return key, self._get_cache().get(key, None)
 
-    def set_entry(self, key, func_res):
-        key_data = {
-            "value": func_res,
-            "time": datetime.now(),
-            "stale": False,
-            "being_calculated": False,
-        }
+    def set_entry(self, key: str, func_res: Any) -> None:
+        key_data = CacheEntry(
+            value=func_res,
+            time=datetime.now(),
+            stale=False,
+            _processing=False,
+            _completed=True,
+        )
         if self.separate_files:
             self._save_cache(key_data, key)
             return  # pragma: no cover
@@ -176,51 +178,51 @@ class _PickleCore(_BaseCore):
             cache[key] = key_data
             self._save_cache(cache)
 
-    def mark_entry_being_calculated_separate_files(self, key):
+    def mark_entry_being_calculated_separate_files(self, key: str) -> None:
         self._save_cache(
-            {
-                "value": None,
-                "time": datetime.now(),
-                "stale": False,
-                "being_calculated": True,
-            },
+            CacheEntry(
+                value=None,
+                time=datetime.now(),
+                stale=False,
+                _processing=True,
+            ),
             key=key,
         )
 
-    def mark_entry_not_calculated_separate_files(self, key):
+    def mark_entry_not_calculated_separate_files(self, key: str) -> None:
         _, entry = self.get_entry_by_key(key)
-        entry["being_calculated"] = False
+        entry._processing = False
         self._save_cache(entry, key=key)
 
-    def mark_entry_being_calculated(self, key):
+    def mark_entry_being_calculated(self, key: str) -> None:
         if self.separate_files:
             self.mark_entry_being_calculated_separate_files(key)
             return  # pragma: no cover
 
         with self.lock:
             cache = self._get_cache()
-            try:
-                cache[key]["being_calculated"] = True
-            except KeyError:
-                cache[key] = {
-                    "value": None,
-                    "time": datetime.now(),
-                    "stale": False,
-                    "being_calculated": True,
-                }
+            if key in cache:
+                cache[key]._processing = True
+            else:
+                cache[key] = CacheEntry(
+                    value=None,
+                    time=datetime.now(),
+                    stale=False,
+                    _processing=True,
+                )
             self._save_cache(cache)
 
-    def mark_entry_not_calculated(self, key):
+    def mark_entry_not_calculated(self, key: str) -> None:
         if self.separate_files:
             self.mark_entry_not_calculated_separate_files(key)
         with self.lock:
             cache = self._get_cache()
             # that's ok, we don't need an entry in that case
-            with suppress(KeyError):
-                cache[key]["being_calculated"] = False
+            if isinstance(cache, dict) and key in cache:
+                cache[key]._processing = False
                 self._save_cache(cache)
 
-    def wait_on_entry_calc(self, key):
+    def wait_on_entry_calc(self, key: str) -> Any:
         if self.separate_files:
             entry = self._get_cache_by_key(key)
             filename = f"{self.cache_fname}_{key}"
@@ -229,8 +231,8 @@ class _PickleCore(_BaseCore):
                 self._reload_cache()
                 entry = self._get_cache()[key]
             filename = self.cache_fname
-        if not entry["being_calculated"]:
-            return entry["value"]
+        if not entry._processing:
+            return entry.value
         event_handler = _PickleCore.CacheChangeHandler(
             filename=filename, core=self, key=key
         )
@@ -245,13 +247,13 @@ class _PickleCore(_BaseCore):
             self.check_calc_timeout(time_spent)
         return event_handler.value
 
-    def clear_cache(self):
+    def clear_cache(self) -> None:
         if self.separate_files:
             self._clear_all_cache_files()
         else:
             self._save_cache({})
 
-    def clear_being_calculated(self):
+    def clear_being_calculated(self) -> None:
         if self.separate_files:
             self._clear_being_calculated_all_cache_files()
             return  # pragma: no cover
@@ -259,5 +261,5 @@ class _PickleCore(_BaseCore):
         with self.lock:
             cache = self._get_cache()
             for key in cache:
-                cache[key]["being_calculated"] = False
+                cache[key]._processing = False
             self._save_cache(cache)

cachier/version.info

@@ -1 +1 @@
-3.0.0
+3.1.0

{cachier-3.0.0.dist-info → cachier-3.1.0.dist-info}/METADATA

@@ -1,33 +1,50 @@
 Metadata-Version: 2.1
 Name: cachier
-Version: 3.0.0
+Version: 3.1.0
 Summary: Persistent, stale-free, local and cross-machine caching for Python functions.
-Home-page: https://github.com/python-cachier/cachier
-Author: Shay Palachy & al.
-Author-email: shay.palachy@gmail.com
-License: MIT
-Keywords: cache,persistence,mongo,memoization,decorator
-Platform: linux
-Platform: osx
-Platform: windows
+Author-email: Shay Palachy Affek <shay.palachy@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2016 Shay Palachy
+        
+        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.
+        
+Project-URL: Source, https://github.com/python-cachier/cachier
+Keywords: cache,caching,cross-machine,decorator,local,memoization,mongo,persistent
 Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
 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: Topic :: Other/Nonlisted Topic
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Utilities
-Classifier: Topic :: Other/Nonlisted Topic
-Classifier: Intended Audience :: Developers
+Description-Content-Type: text/x-rst
 License-File: LICENSE
-Requires-Dist: watchdog >=2.3.1
-Requires-Dist: portalocker >=2.3.2
-Requires-Dist: setuptools >=67.6.0
+Requires-Dist: portalocker>=2.3.2
+Requires-Dist: watchdog>=2.3.1
 
 Cachier
 #######
@@ -492,8 +509,8 @@ Notable bugfixers:
 .. |PyPI-Versions| image:: https://img.shields.io/pypi/pyversions/cachier.svg
    :target: https://pypi.python.org/pypi/cachier
 
-.. |Build-Status| image:: https://github.com/python-cachier/cachier/actions/workflows/test.yml/badge.svg
-  :target: https://github.com/python-cachier/cachier/actions/workflows/test.yml
+.. |Build-Status| image:: https://github.com/python-cachier/cachier/actions/workflows/ci-test.yml/badge.svg
+  :target: https://github.com/python-cachier/cachier/actions/workflows/ci-test.yml
 
 .. |LICENCE| image:: https://img.shields.io/pypi/l/cachier.svg
   :target: https://pypi.python.org/pypi/cachier

cachier-3.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+cachier/__init__.py,sha256=ePVg3SxZQqCXDBSaNVziv5rK8ZjxWsUEAecjvP87-BY,300
+cachier/__main__.py,sha256=upg-TlHs1vngKYvkjoPpl3Pvl6xOx4ut-M1mElMiAo0,443
+cachier/_types.py,sha256=EGJMiw-oCIC_cDLyzw7YC40lfo8jnD3zMmoJpA9Y8Iw,238
+cachier/_version.py,sha256=yE6UYwvdoIRpw3HmNifiGwV3fqVea5PwZj_EvyosiZ8,1079
+cachier/config.py,sha256=KOGaXkBRgv66BexENrTMtrC_TYCeV1fA5v8l6Vj2CYI,3840
+cachier/core.py,sha256=qQa_GT8WQYD-VFcTS8a2v-Hys4_A1no-aM-d3lw1AFY,13149
+cachier/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cachier/version.info,sha256=svRNO24p-LG3PqRzXwBq_8TRmOH9nH1Q5zYVmx72NsY,6
+cachier/cores/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cachier/cores/base.py,sha256=jo69c2RMOXbTzDvqRV0UGa5UvyToipv3f62bICIII1k,3631
+cachier/cores/memory.py,sha256=SSa7qlSU_54YjNYEWrq9rxXozkMYXr5hadAZ3sz62l4,3336
+cachier/cores/mongo.py,sha256=eRG6XP55G4IcWnoMl5xtDufM1szf8FVbOIBbDH_r-Po,4887
+cachier/cores/pickle.py,sha256=20c5pg2CS6wAX1PdefCOjl-orec5w7tqEHVqNbZZv0s,9074
+cachier-3.1.0.dist-info/LICENSE,sha256=-2WrMJkIa0gVP6YQHXXDT7ws-S3M2NEVEF4XF3K8qrY,1069
+cachier-3.1.0.dist-info/METADATA,sha256=pDqPoWSFSkwdCHUQ-kvEzf517DippyuSaf9kDWkUtas,20102
+cachier-3.1.0.dist-info/WHEEL,sha256=OVMc5UfuAQiSplgO0_WdW7vXVGAt9Hdd6qtN4HotdyA,91
+cachier-3.1.0.dist-info/entry_points.txt,sha256=x4Y7t6Y0Qev_3fgG-Jv7TrsvVdJty3FnGAdkT8-_5mY,49
+cachier-3.1.0.dist-info/top_level.txt,sha256=_rW_HiJumDCch67YT-WAgzcyvKg5RiYDMZq9d-0ZpaE,8
+cachier-3.1.0.dist-info/RECORD,,

{cachier-3.0.0.dist-info → cachier-3.1.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.42.0)
+Generator: setuptools (75.2.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

cachier-3.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cachier = cachier.__main__:cli

cachier-3.0.0.dist-info/RECORD

@@ -1,19 +0,0 @@
-cachier/__init__.py,sha256=6i43oFM_ZTp47b6R8Ws2vvf2JXLvbn-TKzWESwBDb-M,304
-cachier/__main__.py,sha256=g8dgovKdDgOMgNIpnmzVRuI5Dj5xODTav45TpZlH_iA,429
-cachier/_types.py,sha256=EGJMiw-oCIC_cDLyzw7YC40lfo8jnD3zMmoJpA9Y8Iw,238
-cachier/_version.py,sha256=yE6UYwvdoIRpw3HmNifiGwV3fqVea5PwZj_EvyosiZ8,1079
-cachier/config.py,sha256=xEWpt_BeaqtrdDdZPnvZN_O3Wp4h6X9_6FfBpMeQZPw,2703
-cachier/core.py,sha256=IdLT2sfguDSvtCyX1EJfgCQnbEDECil1U2JhO5wBP5U,13080
-cachier/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-cachier/version.info,sha256=KYW-iyjTrehY6Nj7S8IvVlsb9gIN_5gtzhQfdyG5mZw,6
-cachier/cores/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-cachier/cores/base.py,sha256=cxtcDfRttGU6YBtq7aO9mAqzEza2y7KhHDZhRbv-aOU,3324
-cachier/cores/memory.py,sha256=JFXnXBAeP0nOXOf_vNgpcEuRNjxre8WQjiUBa7yEYmY,3128
-cachier/cores/mongo.py,sha256=jOcqxIU8wqF2jS2lOfp-VFk5iyVMKHm6AzhFGkxGm0k,4889
-cachier/cores/pickle.py,sha256=dZXUBv7xZKg39IaUERnjPEAcjpDS8sBuObrnxMTqMmk,8871
-cachier-3.0.0.dist-info/LICENSE,sha256=-2WrMJkIa0gVP6YQHXXDT7ws-S3M2NEVEF4XF3K8qrY,1069
-cachier-3.0.0.dist-info/METADATA,sha256=-hfKZSKXrKC7m102SRmJjpcelAZDtD6DoS0gSgm_wv8,18871
-cachier-3.0.0.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
-cachier-3.0.0.dist-info/entry_points.txt,sha256=16JU8wc6a62BLuOXVNjAiXJRp0AB5LtEwiKGYMjZjv0,49
-cachier-3.0.0.dist-info/top_level.txt,sha256=_rW_HiJumDCch67YT-WAgzcyvKg5RiYDMZq9d-0ZpaE,8
-cachier-3.0.0.dist-info/RECORD,,

cachier-3.0.0.dist-info/entry_points.txt

@@ -1,2 +0,0 @@
-[console_scripts]
-cachier = cachier.__naim__:cli