cachier 2.0.1__tar.gz → 2.1.0__tar.gz

{cachier-2.0.1 → cachier-2.1.0}/.github/workflows/test.yml

@@ -32,11 +32,6 @@ jobs:
           python -m pip install --upgrade pip
           python -m pip install -e ".[test]"
       - name: Unit tests
-        env:
-          CACHIER_TEST_HOST: ${{ secrets.CACHIER_TEST_HOST  }}
-          CACHIER_TEST_DB: ${{ secrets.CACHIER_TEST_DB  }}
-          CACHIER_TEST_USERNAME: ${{ secrets.CACHIER_TEST_USERNAME  }}
-          CACHIER_TEST_PASSWORD: ${{ secrets.CACHIER_TEST_PASSWORD  }}
         run: |
           pytest
       - name: "Upload coverage to Codecov"

{cachier-2.0.1 → cachier-2.1.0}/PKG-INFO

@@ -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
@@ -111,6 +111,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
@@ -121,7 +148,7 @@ The Cachier wrapper adds a ``clear_cache()`` function to each wrapped function.
 
   foo.clear_cache()
 
-Genereal Configuration
+General Configuration
 ----------------------
 
 Threads Limit
@@ -163,11 +190,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
 
@@ -176,6 +207,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
 ---------------------------
 
@@ -365,7 +413,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.
 
@@ -411,5 +459,3 @@ Notable bugfixers:
 .. _watchdog: https://github.com/gorakhargosh/watchdog
 
 
-
-

{cachier-2.0.1 → cachier-2.1.0}/README.rst

@@ -83,6 +83,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
@@ -93,7 +120,7 @@ The Cachier wrapper adds a ``clear_cache()`` function to each wrapped function.
 
   foo.clear_cache()
 
-Genereal Configuration
+General Configuration
 ----------------------
 
 Threads Limit
@@ -135,11 +162,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
 
@@ -148,6 +179,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
 ---------------------------
 
@@ -337,7 +385,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.
 
@@ -381,5 +429,3 @@ Notable bugfixers:
 .. links:
 .. _pymongo: https://api.mongodb.com/python/current/
 .. _watchdog: https://github.com/gorakhargosh/watchdog
-
-

{cachier-2.0.1 → cachier-2.1.0}/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-2.0.1 → cachier-2.1.0}/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-2.0.1 → cachier-2.1.0}/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-2.0.1 → cachier-2.1.0}/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-2.0.1 → cachier-2.1.0}/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-2.0.1 → cachier-2.1.0}/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-2.0.1 → cachier-2.1.0}/cachier.egg-info/PKG-INFO

@@ -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
@@ -111,6 +111,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
@@ -121,7 +148,7 @@ The Cachier wrapper adds a ``clear_cache()`` function to each wrapped function.
 
   foo.clear_cache()
 
-Genereal Configuration
+General Configuration
 ----------------------
 
 Threads Limit
@@ -163,11 +190,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
 
@@ -176,6 +207,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
 ---------------------------
 
@@ -365,7 +413,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.
 
@@ -411,5 +459,3 @@ Notable bugfixers:
 .. _watchdog: https://github.com/gorakhargosh/watchdog
 
 
-
-

{cachier-2.0.1 → cachier-2.1.0}/cachier.egg-info/SOURCES.txt

@@ -33,10 +33,12 @@ cachier.egg-info/top_level.txt
 cachier/scripts/__init__.py
 cachier/scripts/cli.py
 tests/__init__.py
-tests/conftest.py
 tests/speed_eval.py
+tests/standalone_script.py
 tests/test_core_lookup.py
 tests/test_general.py
 tests/test_memory_core.py
 tests/test_mongo_core.py
-tests/test_pickle_core.py
+tests/test_pickle_core.py
+tests/test_quality.py
+tests/test_security.py

{cachier-2.0.1 → cachier-2.1.0}/cachier.egg-info/requires.txt

@@ -1,14 +1,19 @@
 watchdog
 portalocker
 pathtools
+setuptools>=67.6.0
 
 [test]
 pytest
 coverage
 pytest-cov
-birch
+bandit
+flake8
+pylint
+safety
 pymongo
 dnspython
+pymongo-inmemory
 pandas
 collective.checkdocs
 pygments

{cachier-2.0.1 → cachier-2.1.0}/setup.py

@@ -18,10 +18,10 @@ import versioneer
 TEST_REQUIRES = [
     # tests and coverages
     'pytest', 'coverage', 'pytest-cov',
-    # for reading configfutation
-    'birch',
+    # linting and code quality
+    'bandit', 'flake8', 'pylint', 'safety',
     # to connect to the test mongodb server
-    'pymongo', 'dnspython',
+    'pymongo', 'dnspython', 'pymongo-inmemory',
     # to test pandas dataframe as-param hashing with mongodb core
     'pandas',
     # to be able to run `python setup.py checkdocs`
@@ -44,7 +44,7 @@ setup(
     author='Shay Palachy',
     author_email='shay.palachy@gmail.com',
     url='https://github.com/python-cachier/cachier',
-    packages=['cachier'],
+    packages=['cachier', 'cachier.scripts'],
     entry_points='''
         [console_scripts]
         cachier=cachier.scripts.cli:cli
@@ -52,6 +52,7 @@ setup(
     install_requires=[
         'watchdog', 'portalocker',
         'pathtools',  # for watchdog, who has dependency spec problem
+        'setuptools>=67.6.0',  # to avoid vulnerability in 56.0.0
     ],
     extras_require={
         'test': TEST_REQUIRES,

{cachier-2.0.1 → cachier-2.1.0}/tests/speed_eval.py

@@ -18,7 +18,7 @@ def _test_int_pickling_compare(int_1, int_2):
 def test_pickle_speed():
     """Test speeds"""
     print("Comparing speeds of decorated vs non-decorated functions...")
-    num_of_vals = 100
+    num_of_vals = 1000
     times = []
     for i in range(1, num_of_vals):
         tic = time()

cachier-2.1.0/tests/standalone_script.py

@@ -0,0 +1,11 @@
+import cachier
+import time
+
+
+@cachier.cachier()
+def _takes_3_seconds(label, value):
+    time.sleep(3)
+    return f'{label} {value}'
+
+
+print(_takes_3_seconds('two', 2))