From 4e16a6e9b8921a58fbdcc8caacaf437c1be1c545 Mon Sep 17 00:00:00 2001 From: Shay Palachy Date: Thu, 20 Apr 2017 14:55:18 +0300 Subject: [PATCH] readme additions --- .travis.yml | 24 +++++++++++----------- README.rst | 48 ++++++++++++++++++++++++++++++++++++------- cachier/core.py | 2 +- cachier/mongo_core.py | 19 ++++++++++------- setup.py | 2 +- 5 files changed, 67 insertions(+), 28 deletions(-) diff --git a/.travis.yml b/.travis.yml index b6b855e..99531a8 100644 --- a/.travis.yml +++ b/.travis.yml @@ -17,15 +17,15 @@ script: python -m pytest --cov=cachier after_success: # - coveralls - codecov -deploy: - provider: pypi - user: shaypal5 - password: - secure: RaTkue2YoXAkT/byvecFuOYdrJpHchCSMYnV4xqUFhQgT8qbyv7/EL+pm6sQ75Ni/JKAhSBdW8l4faKY9X1vW3yc5E2YHBf/81VJo1+JAbD9vGX0RLZbDzIsEVht+hL2Xxvab5Xh3fI7Pcr+cozKKMZxcOvEEwGo5DENM4CquGLeYyUxQOyhwSVjA+54bucFm+u+BA0QxUSHSyFy0cPKJVi8jNMSK/XAvs+Zk26o/MOU3udSj25FBtTkqPTBphaUNkt2EPGK1ZWkS9uhqs+hrETMWj6n6k49WblXvMDJiUtCIM+36Q+GBH/9UxCWuMOjL+uRFjVwwKQEcend9YMvp4+jRZ1HsLAWjMMhazxgkZ6M7bErHRxyabb7om+5IMptPdIo31gw8S1dKktGyuiSVYqs9X2mGA//SoItoDjIAUI81TQ3s2QLw5SfyEARfAdN+QS2aRaZHc0RPcLb10xNu7d7cy/4I88W+dptNqVABCP26Jlg4xsrRGMnONMSt/kWg1enXfgSXJcyrqqAaZzQUs/5QmVGtU4DBl3C8pUiHs6eGdpcqO3vpYoHveNT0WzoONkqZBvzBOjUWf8oMJzI3LcmCruUtktyd9cnlzM49pndnCyXPIKcpqPSGtR0FS3I/QhP7RBB+5xjP39SIuFsEW6ciakOs+AdMePl8tAq01o= - distributions: sdist bdist_wheel - on: - all_branches: true - tags: true - repo: shaypal5/cachier - condition: $TRAVIS_PYTHON_VERSION = "3.5" - skip_upload_docs: true +# deploy: +# provider: pypi +# user: shaypal5 +# password: +# secure: RaTkue2YoXAkT/byvecFuOYdrJpHchCSMYnV4xqUFhQgT8qbyv7/EL+pm6sQ75Ni/JKAhSBdW8l4faKY9X1vW3yc5E2YHBf/81VJo1+JAbD9vGX0RLZbDzIsEVht+hL2Xxvab5Xh3fI7Pcr+cozKKMZxcOvEEwGo5DENM4CquGLeYyUxQOyhwSVjA+54bucFm+u+BA0QxUSHSyFy0cPKJVi8jNMSK/XAvs+Zk26o/MOU3udSj25FBtTkqPTBphaUNkt2EPGK1ZWkS9uhqs+hrETMWj6n6k49WblXvMDJiUtCIM+36Q+GBH/9UxCWuMOjL+uRFjVwwKQEcend9YMvp4+jRZ1HsLAWjMMhazxgkZ6M7bErHRxyabb7om+5IMptPdIo31gw8S1dKktGyuiSVYqs9X2mGA//SoItoDjIAUI81TQ3s2QLw5SfyEARfAdN+QS2aRaZHc0RPcLb10xNu7d7cy/4I88W+dptNqVABCP26Jlg4xsrRGMnONMSt/kWg1enXfgSXJcyrqqAaZzQUs/5QmVGtU4DBl3C8pUiHs6eGdpcqO3vpYoHveNT0WzoONkqZBvzBOjUWf8oMJzI3LcmCruUtktyd9cnlzM49pndnCyXPIKcpqPSGtR0FS3I/QhP7RBB+5xjP39SIuFsEW6ciakOs+AdMePl8tAq01o= +# distributions: sdist bdist_wheel +# on: +# all_branches: true +# tags: true +# repo: shaypal5/cachier +# condition: $TRAVIS_PYTHON_VERSION = "3.5" +# skip_upload_docs: true diff --git a/README.rst b/README.rst index f2cd602..0ef888a 100644 --- a/README.rst +++ b/README.rst @@ -3,7 +3,7 @@ Cachier |PyPI-Status| |PyPI-Versions| |Build-Status| |LICENCE| -Persistent, stale-free cache / memoization decorators for Python. +Persistent, stale-free, local and cross-machine caching for Python functions. .. code-block:: python @@ -42,7 +42,7 @@ Install ``cachier`` with: Features ======== -* Tested on Linux and OS X systems. Does not support windows. +* Tested on Linux and OS X systems. Does not support Windows. * Compatible with Python 2.7+ and Python 3.5+. * A simple interface. * Defining "shelf life" for cached values. @@ -90,8 +90,11 @@ The Cachier wrapper adds a ``clear_cache()`` function to each wrapped function. foo.clear_cache() -Setting Shelf Live ------------------- +Cache Shelf Life +---------------- + +Setting Shelf Life +~~~~~~~~~~~~~~~~~~ You can set any duration as the shelf life of cached return values of a function by providing a corresponding ``timedelta`` object to the ``stale_after`` parameter: .. code-block:: python @@ -106,8 +109,8 @@ Now when a cached value matching the given arguments is found the time of its ca This is usefull for lengthy calculations that depend on a dynamic data source. -Fuzzy Shelf Live ----------------- +Fuzzy Shelf Life +~~~~~~~~~~~~~~~~ Sometimes you may want your function to trigger a calculation when it encounters a stale result, but still not wait on it if it's not that critical. In that case you can set ``next_time`` to ``True`` to have your function trigger a recalculation **in a separate thread**, but return the currently cached stale value: .. code-block:: python @@ -117,6 +120,37 @@ Sometimes you may want your function to trigger a calculation when it encounters Further function calls made while the calculation is being performed will not trigger redundant calculations. +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 to modify its behaviour for a specific function call. + +Ignore Cache +~~~~~~~~~~~~ + +You cah have ``cachier`` ignore any existing cache for a specific function call by passing ``ignore_cache=True`` to the function call. The cache will neither be checked nor updated with the new return value. + +.. code-block:: python + + @cachier() + def sum(first_num, second_num): + return first_num + second_num + + def main(): + print(sum(5, 3, ignore_cache=True)) + +Overwrite Cache +~~~~~~~~~~~~~~~ + +You cah have ``cachier`` overwrite an existing cache entry - if one exists - for a specific function call by passing ``overwrite_cache=True`` to the function call. The cache will not be checked, but will be updated with the new return value. + +Verbose Cache Call +~~~~~~~~~~~~~~~~~~ + +You cah have ``cachier`` print out a detailed explanation of the logic of a specific call by passing ``verbose_cachee=True`` to the function call. This can be usefull if you are not sure why a certain function result is or is not returned. + + + Cachier Cores ============= @@ -142,7 +176,7 @@ You can set a MongoDB-based cache by assigning ``mongetter`` with a callable tha @cachier(mongetter=False) -This allows you to have a cross-machine, albeit slower, cache. +This allows you to have a cross-machine, albeit slower, cache. This functionality requires that the installation of the ``pymongo`` python package. Credits diff --git a/cachier/core.py b/cachier/core.py index c7c4141..778a85e 100644 --- a/cachier/core.py +++ b/cachier/core.py @@ -125,8 +125,8 @@ def cachier(stale_after=None, next_time=False, pickle_reload=True, @wraps(func) def func_wrapper(*args, **kwds): # pylint: disable=C0111,R0911 # print('Inside general wrapper for {}.'.format(func.__name__)) - overwrite_cache = kwds.pop('overwrite_cache', False) ignore_cache = kwds.pop('ignore_cache', False) + overwrite_cache = kwds.pop('overwrite_cache', False) verbose_cache = kwds.pop('verbose_cache', False) if ignore_cache: return func(*args, **kwds) diff --git a/cachier/mongo_core.py b/cachier/mongo_core.py index da8d1e0..d6c0c40 100644 --- a/cachier/mongo_core.py +++ b/cachier/mongo_core.py @@ -9,14 +9,19 @@ import pickle # for serialization of python objects from datetime import datetime -import time # to sleep when waiting on Mongo cache +import time # to sleep when waiting on Mongo cache\ +import warnings -from pymongo import ( - IndexModel, - ASCENDING -) -from pymongo.errors import OperationFailure -from bson.binary import Binary # to save binary data to mongodb +try: + from pymongo import ( + IndexModel, + ASCENDING + ) + from pymongo.errors import OperationFailure + from bson.binary import Binary # to save binary data to mongodb +except ImportError: + warnings.warn( + "Cachier warning: pymongo was not found. MongoDB cores will not work.") from .base_core import _BaseCore diff --git a/setup.py b/setup.py index f1ed58c..0e9a980 100644 --- a/setup.py +++ b/setup.py @@ -26,7 +26,7 @@ setup( name='cachier', version=versioneer.get_version(), cmdclass=versioneer.get_cmdclass(), - description='Persistent, stale-free memoization decorators for Python.', + description='Persistent, stale-free, local and cross-machine caching for Python functions.', long_description=README_RST, license='MIT', author='Shay Palachy',