cachier 2.0.1__py2.py3-none-any.whl → 2.1.0__py2.py3-none-any.whl

cachier/_version.py

@@ -11,8 +11,8 @@ version_json = '''
 {
  "dirty": false,
  "error": null,
- "full-revisionid": "15ce5f36320f15e8058baf29015fa27ea493d211",
- "version": "2.0.1"
+ "full-revisionid": "7be769b78acf3a0e0aff8d528476913571d79749",
+ "version": "2.1.0"
 }
 '''  # END VERSION_JSON
 

cachier/base_core.py

@@ -8,24 +8,32 @@
 
 import abc  # for the _BaseCore abstract base class
 import functools
+import hashlib
+import inspect
+import pickle  # nosec: B403
 
 
-# pylint: disable-next=protected-access
-_default_hash_params = functools.partial(functools._make_key, typed=False)
+def _default_hash_func(args, kwds):
+    # pylint: disable-next=protected-access
+    key = functools._make_key(args, kwds, typed=True)
+    hash = hashlib.sha256()
+    for item in key:
+        hash.update(pickle.dumps(item))
+    return hash.hexdigest()
 
 
 class _BaseCore():
     __metaclass__ = abc.ABCMeta
 
-    def __init__(self, stale_after, next_time, hash_params):
-        self.stale_after = stale_after
-        self.next_time = next_time
-        self.hash_func = hash_params if hash_params else _default_hash_params
+    def __init__(self, hash_func):
+        self.hash_func = hash_func if hash_func else _default_hash_func
         self.func = None
 
     def set_func(self, func):
-        """Sets the function this core will use. This has to be set before
-        any method is called"""
+        """Sets the function this core will use. This has to be set before any
+        method is called. Also determine if the funtion is an object method."""
+        func_params = list(inspect.signature(func).parameters)
+        self.func_is_method = func_params and func_params[0] == 'self'
         self.func = func
 
     def get_entry(self, args, kwds):
@@ -34,6 +42,12 @@ class _BaseCore():
         key = self.hash_func(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."""
+        key = self.hash_func(args, kwds)
+        self.set_entry(key, value_to_cache)
+        return value_to_cache
+
     @abc.abstractmethod
     def get_entry_by_key(self, key):
         """Returns the result mapped to the given key in this core's cache,

cachier/core.py

@@ -14,6 +14,7 @@ from __future__ import print_function
 
 import os
 from functools import wraps
+from warnings import warn
 
 import datetime
 from concurrent.futures import ThreadPoolExecutor
@@ -85,6 +86,7 @@ def cachier(
     backend=None,
     mongetter=None,
     cache_dir=None,
+    hash_func=None,
     hash_params=None,
     wait_for_calc_timeout=0,
     separate_files=False,
@@ -125,7 +127,7 @@ def cachier(
         A fully qualified path to a file directory to be used for cache files.
         The running process must have running permissions to this folder. If
         not provided, a default directory at `~/.cachier/` is used.
-    hash_params : callable, optional
+    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
@@ -141,15 +143,19 @@ def cachier(
         split between several files, one for each argument set. This can help
         if you per-function cache files become too large.
     """
+    # Check for deprecated parameters
+    if hash_params is not None:
+        message = 'hash_params will be removed in a future release, ' \
+                  'please use hash_func instead'
+        warn(message, DeprecationWarning, stacklevel=2)
+        hash_func = hash_params
     # The default is calculated dynamically to maintain previous behavior
     # to default to pickle unless the ``mongetter`` argument is given.
     if backend is None:
         backend = 'pickle' if mongetter is None else 'mongo'
     if backend == 'pickle':
         core = _PickleCore(  # pylint: disable=R0204
-            stale_after=stale_after,
-            next_time=next_time,
-            hash_params=hash_params,
+            hash_func=hash_func,
             reload=pickle_reload,
             cache_dir=cache_dir,
             separate_files=separate_files,
@@ -161,16 +167,12 @@ def cachier(
                 'must specify ``mongetter`` when using the mongo core')
         core = _MongoCore(
             mongetter=mongetter,
-            stale_after=stale_after,
-            next_time=next_time,
-            hash_params=hash_params,
+            hash_func=hash_func,
             wait_for_calc_timeout=wait_for_calc_timeout,
         )
     elif backend == 'memory':
         core = _MemoryCore(
-            stale_after=stale_after,
-            next_time=next_time,
-            hash_params=hash_params,
+            hash_func=hash_func,
         )
     elif backend == 'redis':
         raise NotImplementedError(
@@ -194,7 +196,10 @@ def cachier(
                 _print = print
             if ignore_cache:
                 return func(*args, **kwds)
-            key, entry = core.get_entry(args, kwds)
+            if core.func_is_method:
+                key, entry = core.get_entry(args[1:], kwds)
+            else:
+                key, entry = core.get_entry(args, kwds)
             if overwrite_cache:
                 return _calc_entry(core, key, func, args, kwds)
             if entry is not None:  # pylint: disable=R0101
@@ -259,9 +264,20 @@ def cachier(
             except AttributeError:
                 return None
 
+        def precache_value(*args, value_to_cache, **kwds):
+            """Add an initial value to the cache.
+
+            Arguments
+            ---------
+            value : any
+                entry to be written into the cache
+            """
+            return core.precache_value(args, kwds, value_to_cache)
+
         func_wrapper.clear_cache = clear_cache
         func_wrapper.clear_being_calculated = clear_being_calculated
         func_wrapper.cache_dpath = cache_dpath
+        func_wrapper.precache_value = precache_value
         return func_wrapper
 
     return _cachier_decorator

cachier/memory_core.py

@@ -17,8 +17,8 @@ class _MemoryCore(_BaseCore):
         See :class:`_BaseCore` documentation.
     """
 
-    def __init__(self, stale_after, next_time, hash_params):
-        super().__init__(stale_after, next_time, hash_params)
+    def __init__(self, hash_func):
+        super().__init__(hash_func)
         self.cache = {}
         self.lock = threading.RLock()
 

cachier/mongo_core.py

@@ -37,14 +37,12 @@ class _MongoCore(_BaseCore):
 
     _INDEX_NAME = 'func_1_key_1'
 
-    def __init__(
-            self, mongetter, stale_after, next_time,
-            hash_params, wait_for_calc_timeout):
+    def __init__(self, mongetter, hash_func, wait_for_calc_timeout):
         if 'pymongo' not in sys.modules:
             warnings.warn((
                 "Cachier warning: pymongo was not found. "
                 "MongoDB cores will not function."))
-        super().__init__(stale_after, next_time, hash_params)
+        super().__init__(hash_func)
         self.mongetter = mongetter
         self.mongo_collection = self.mongetter()
         self.wait_for_calc_timeout = wait_for_calc_timeout

cachier/pickle_core.py

@@ -29,10 +29,6 @@ class _PickleCore(_BaseCore):
 
     Parameters
     ----------
-    stale_after : datetime.timedelta, optional
-        See _BaseCore documentation.
-    next_time : bool, optional
-        See _BaseCore documentation.
     pickle_reload : bool, optional
         See core.cachier() documentation.
     cache_dir : str, optional.
@@ -84,10 +80,10 @@ class _PickleCore(_BaseCore):
             self._check_calculation()
 
     def __init__(
-            self, stale_after, next_time, hash_params, reload,
-            cache_dir, separate_files, wait_for_calc_timeout,
+            self, hash_func, reload, cache_dir,
+            separate_files, wait_for_calc_timeout,
     ):
-        super().__init__(stale_after, next_time, hash_params)
+        super().__init__(hash_func)
         self.cache = None
         self.reload = reload
         self.cache_dir = DEF_CACHIER_DIR

cachier/scripts/cli.py

@@ -0,0 +1,17 @@
+"""A command-line interface for cachier."""
+
+import click
+
+from cachier.core import _set_max_workers
+
+
+@click.group()
+def cli():
+    """A command-line interface for cachier."""
+
+
+@cli.command("Limits the number of worker threads used by cachier.")
+@click.argument('max_workers', nargs=1, type=int)
+def set_max_workers(max_workers):
+    """Limits the number of worker threads used by cachier."""
+    _set_max_workers(max_workers)

{cachier-2.0.1.dist-info → cachier-2.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cachier
-Version: 2.0.1
+Version: 2.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
@@ -27,13 +27,18 @@ License-File: LICENSE
 Requires-Dist: watchdog
 Requires-Dist: portalocker
 Requires-Dist: pathtools
+Requires-Dist: setuptools (>=67.6.0)
 Provides-Extra: test
 Requires-Dist: pytest ; extra == 'test'
 Requires-Dist: coverage ; extra == 'test'
 Requires-Dist: pytest-cov ; extra == 'test'
-Requires-Dist: birch ; extra == 'test'
+Requires-Dist: bandit ; extra == 'test'
+Requires-Dist: flake8 ; extra == 'test'
+Requires-Dist: pylint ; extra == 'test'
+Requires-Dist: safety ; extra == 'test'
 Requires-Dist: pymongo ; extra == 'test'
 Requires-Dist: dnspython ; extra == 'test'
+Requires-Dist: pymongo-inmemory ; extra == 'test'
 Requires-Dist: pandas ; extra == 'test'
 Requires-Dist: collective.checkdocs ; extra == 'test'
 Requires-Dist: pygments ; extra == 'test'
@@ -123,6 +128,33 @@ You can add a default, pickle-based, persistent cache to your function - meaning
     """Your function now has a persistent cache mapped by argument values!"""
     return {'arg1': arg1, 'arg2': arg2}
 
+Class and object methods can also be cached. Cachier will automatically ignore the `self` parameter when determining the cache key for an object method. **This means that methods will be cached across all instances of an object, which may not be what you want.**
+
+.. code-block:: python
+
+  from cachier import cachier
+
+  class Foo():
+    @staticmethod
+    @cachier()
+    def good_static_usage(arg_1, arg_2):
+      return arg_1 + arg_2
+
+    # Instance method does not depend on object's internal state, so good to cache
+    @cachier()
+    def good_usage_1(self, arg_1, arg_2)
+      return arg_1 + arg_2
+
+    # Instance method is calling external service, probably okay to cache
+    @cachier()
+    def good_usage_2(self, arg_1, arg_2)
+      result = self.call_api(arg_1, arg_2)
+      return result
+
+    # Instance method relies on object attribute, NOT good to cache
+    @cachier()
+    def bad_usage(self, arg_1, arg_2)
+      return arg_1 + arg_2 + self.arg_3
 
 
 Resetting a Cache
@@ -133,7 +165,7 @@ The Cachier wrapper adds a ``clear_cache()`` function to each wrapped function.
 
   foo.clear_cache()
 
-Genereal Configuration
+General Configuration
 ----------------------
 
 Threads Limit
@@ -175,11 +207,15 @@ Further function calls made while the calculation is being performed will not tr
 Working with unhashable arguments
 ---------------------------------
 
-As mentioned above, the positional and keyword arguments to the wrapped function must be hashable (i.e. Python's immutable built-in objects, not mutable containers). To get around this limitation the ``hash_params`` parameter of the ``cachier`` decorator can be provided with a callable that gets the args and kwargs from the decorated function and returns a hash key for them.
+As mentioned above, the positional and keyword arguments to the wrapped function must be hashable (i.e. Python's immutable built-in objects, not mutable containers). To get around this limitation the ``hash_func`` parameter of the ``cachier`` decorator can be provided with a callable that gets the args and kwargs from the decorated function and returns a hash key for them.
 
 .. code-block:: python
 
-  @cachier(hash_params=hash_my_custom_class)
+  def calculate_hash(args, kwds):
+    key = ...  # compute a hash key here based on arguments
+    return key
+
+  @cachier(hash_func=calculate_hash)
   def calculate_super_complex_stuff(custom_obj):
     # amazing code goes here
 
@@ -188,6 +224,23 @@ See here for an example:
 `Question: How to work with unhashable arguments <https://github.com/python-cachier/cachier/issues/91>`_
 
 
+Precaching values
+---------------------------------
+
+If you want to load a value into the cache without calling the underlying function, this can be done with the `precache_value` function.
+
+.. code-block:: python
+
+  @cachier()
+  def add(arg1, arg2):
+    return arg1 + arg2
+
+  add.precache_value(2, 2, value_to_cache=5)
+
+  result = add(2, 2)
+  print(result)  # prints 5
+
+
 Per-function call arguments
 ---------------------------
 
@@ -377,7 +430,7 @@ Other major contributors:
 
   * `cthoyt <https://github.com/cthoyt>`_ - Base memory core implementation.
 
-  * `amarczew <https://github.com/amarczew>`_ - The ``hash_params`` kwarg.
+  * `amarczew <https://github.com/amarczew>`_ - The ``hash_func`` kwarg.
 
   * `non-senses <https://github.com/non-senses>`_ - The ``wait_for_calc_timeout`` kwarg.
 
@@ -423,5 +476,3 @@ Notable bugfixers:
 .. _watchdog: https://github.com/gorakhargosh/watchdog
 
 
-
-

cachier-2.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+cachier/__init__.py,sha256=znE73J-Sg_4tjDmfKaJ5Cabg_kWhus9yhq1LJmM8B6Q,133
+cachier/_version.py,sha256=Gk55atXZn9Zmgvi_28RCi_UXaHw85U1VAatxQ7cEXK0,471
+cachier/base_core.py,sha256=3TJOmzCwtoGAGsMj-4zo91C6eP69cSB-40Lru3MFgBg,2663
+cachier/core.py,sha256=L0dWlbERd-8RiGPP3Iw1sbNzgclO7wSSflS4QbkaQmY,11454
+cachier/memory_core.py,sha256=do4aKTxcNaoaCpLx6w2bhhLIAze8tEo9gPNAekwWrHo,3020
+cachier/mongo_core.py,sha256=Tbe-fpWyvlYK_WQq02-K2WDGqtoz90rwcTS_DFT146I,5114
+cachier/pickle_core.py,sha256=4-sji-yQNfTvutpxHBHzZbourHyby_7ykGQFLf8dC58,10150
+cachier/scripts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cachier/scripts/cli.py,sha256=tMwq1IaD_lxhcc8WMgWh4P0gpi5l6-twCS2YeAKAM98,429
+cachier-2.1.0.dist-info/LICENSE,sha256=-2WrMJkIa0gVP6YQHXXDT7ws-S3M2NEVEF4XF3K8qrY,1069
+cachier-2.1.0.dist-info/METADATA,sha256=ysQu-4vNtUdDT2wQjGAsrgfzZNOWaEWKPKdTinfOM_8,16470
+cachier-2.1.0.dist-info/WHEEL,sha256=z9j0xAa_JmUKMpmz72K0ZGALSM_n-wQVmGbleXx2VHg,110
+cachier-2.1.0.dist-info/entry_points.txt,sha256=HZPL3TEoT-aieCOvQvsLEDBAuPBSbDNrIjMiDA8h6zE,71
+cachier-2.1.0.dist-info/top_level.txt,sha256=_rW_HiJumDCch67YT-WAgzcyvKg5RiYDMZq9d-0ZpaE,8
+cachier-2.1.0.dist-info/RECORD,,

cachier-2.0.1.dist-info/RECORD

@@ -1,13 +0,0 @@
-cachier/__init__.py,sha256=znE73J-Sg_4tjDmfKaJ5Cabg_kWhus9yhq1LJmM8B6Q,133
-cachier/_version.py,sha256=a5msFbwD6NYMINT1KG0orJkvdk7TUYcBzgZ2eQgM_Ts,471
-cachier/base_core.py,sha256=PT2fhBy4P8PyaBy_iR6FFbTStDBMeNtF_FVMY7ax7ww,2157
-cachier/core.py,sha256=h3dCDlBdUYSsJ2AOUVl-IbNjE6H5NH9y-nlzlxXWYoI,10869
-cachier/memory_core.py,sha256=5PGm1avW_nHlctvJrYWlerLWgttKpP69epOt2e5r1O0,3072
-cachier/mongo_core.py,sha256=-YOjOOMVCu1bVb26nge2b4vatxFwafAyA52RKzhL9xc,5191
-cachier/pickle_core.py,sha256=b7QtVjuRvcUnC2ecabMmH7Zu8JYXF251cWWTFv4Iv48,10354
-cachier-2.0.1.dist-info/LICENSE,sha256=-2WrMJkIa0gVP6YQHXXDT7ws-S3M2NEVEF4XF3K8qrY,1069
-cachier-2.0.1.dist-info/METADATA,sha256=0wGUUQ0pfQEq3uh8gIDpkmU0Gjil3NX_K8xPJm5jQSg,14837
-cachier-2.0.1.dist-info/WHEEL,sha256=z9j0xAa_JmUKMpmz72K0ZGALSM_n-wQVmGbleXx2VHg,110
-cachier-2.0.1.dist-info/entry_points.txt,sha256=HZPL3TEoT-aieCOvQvsLEDBAuPBSbDNrIjMiDA8h6zE,71
-cachier-2.0.1.dist-info/top_level.txt,sha256=_rW_HiJumDCch67YT-WAgzcyvKg5RiYDMZq9d-0ZpaE,8
-cachier-2.0.1.dist-info/RECORD,,