Package: cachier
Persistent, stale-free, local and cross-machine caching for Python functions.fromcachierimportcachierimportdatetime@cachier(stale_after=datetime.timedelta(days=3))deffoo(arg1,arg2):"""foo now has a persistent cache, triggering recalculation for values stored more than 3 days."""return{'arg1':arg1,'arg2':arg2}ContentsInstallationFeaturesFuture featuresUseSetting up a CacheResetting a CacheGeneral ConfigurationGlobal DefaultsThreads LimitGlobal Enable/DisableCache Shelf LifeSetting Shelf LifeFuzzy Shelf LifeWorking with unhashable argumentsPrecaching valuesPer-function call argumentsIgnore CacheOverwrite CacheVerbose Cache CallCacheNoneValuesCachier CoresPickle CoreMongoDB CoreMemory CoreContributingInstalling for developmentRunning the testsRunning MongoDB tests against a live MongoDB instanceAdding documentationCreditsInstallationInstallcachierwith:pipinstallcachierFor the latest version supporting Python 2.7 please use:pipinstall'cachier==1.2.8'FeaturesPure Python.Compatible with Python 3.8+ (Python 2.7 was discontinued in version 1.2.8).Supported andtested on Linux, OS X and Windows.A simple interface.Defining “shelf life” for cached values.Local caching using pickle files.Cross-machine caching using MongoDB.Thread-safety.Cachier isNOT:Meant as a transient cache. Python’s @lru_cache is better.Especially fast. It is meant to replace function calls that take more than… a second, say (overhead is around 1 millisecond).Future featuresS3 core.Multi-core caching.Cache replacement policiesUseCachier provides a decorator which you can wrap around your functions to give them a persistent cache. The positional and keyword arguments to the wrapped function must be hashable (i.e. Python’s immutable built-in objects, not mutable containers). Also, notice that since objects which are instances of user-defined classes are hashable but all compare unequal (their hash value is their id), equal objects across different sessions will not yield identical keys.Setting up a CacheYou can add a default, pickle-based, persistent cache to your function - meaning it will last across different Python kernels calling the wrapped function - by decorating it with thecachierdecorator (notice the()!).fromcachierimportcachier@cachier()deffoo(arg1,arg2):"""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 theselfparameter 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.fromcachierimportcachierclassFoo():@staticmethod@cachier()defgood_static_usage(arg_1,arg_2):returnarg_1+arg_2# Instance method does not depend on object's internal state, so good to cache@cachier()defgood_usage_1(self,arg_1,arg_2):returnarg_1+arg_2# Instance method is calling external service, probably okay to cache@cachier()defgood_usage_2(self,arg_1,arg_2):result=self.call_api(arg_1,arg_2)returnresult# Instance method relies on object attribute, NOT good to cache@cachier()defbad_usage(self,arg_1,arg_2):returnarg_1+arg_2+self.arg_3Resetting a CacheThe Cachier wrapper adds aclear_cache()function to each wrapped function. To reset the cache of the wrapped function simply call this method:foo.clear_cache()General ConfigurationGlobal DefaultsSettings can be globally configured across all Cachier wrappers through the use of theset_default_paramsfunction. This function takes the same keyword parameters as the ones defined in the decorator, which can be passed all at once or with multiple calls. Parameters given directly to a decorator take precedence over any values set by this function.The following parameters will only be applied to decorators defined afterset_default_paramsis called:hash_funcbackendmongettercache_dirpickle_reloadseparate_filesThese parameters can be changed at any time and they will apply to all decorators:allow_nonecaching_enabledstale_afternext_timewait_for_calc_timeoutThe current defaults can be fetched by callingget_default_params.Threads LimitTo limit the number of threads Cachier is allowed to spawn, set theCACHIER_MAX_WORKERSwith the desired number. The default is 8, so to enable Cachier to spawn even more threads, you’ll have to set a higher limit explicitly.Global Enable/DisableCaching can be turned off across all decorators by callingdisable_caching, and then re-activated by callingenable_caching.These functions are convenience wrappers around thecaching_enableddefault setting.Cache Shelf LifeSetting Shelf LifeYou can set any duration as the shelf life of cached return values of a function by providing a correspondingtimedeltaobject to thestale_afterparameter:importdatetime@cachier(stale_after=datetime.timedelta(weeks=2))defbar(arg1,arg2):return{'arg1':arg1,'arg2':arg2}Now when a cached value matching the given arguments is found the time of its calculation is checked; if more thanstale_aftertime has since passed, the function will be run again for the same arguments and the new value will be cached and returned.This is useful for lengthy calculations that depend on a dynamic data source.Fuzzy Shelf LifeSometimes 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 setnext_timetoTrueto have your function trigger a recalculationin a separate thread, but return the currently cached stale value:@cachier(next_time=True)Further function calls made while the calculation is being performed will not trigger redundant calculations.Working with unhashable argumentsAs 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 thehash_funcparameter of thecachierdecorator can be provided with a callable that gets the args and kwargs from the decorated function and returns a hash key for them.defcalculate_hash(args,kwds):key=...# compute a hash key here based on argumentsreturnkey@cachier(hash_func=calculate_hash)defcalculate_super_complex_stuff(custom_obj):# amazing code goes hereSee here for an example:Question: How to work with unhashable argumentsPrecaching valuesIf you want to load a value into the cache without calling the underlying function, this can be done with theprecache_valuefunction.@cachier()defadd(arg1,arg2):returnarg1+arg2add.precache_value(2,2,value_to_cache=5)result=add(2,2)print(result)# prints 5Per-function call argumentsCachier 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.Ignore CacheYou can havecachierignore any existing cache for a specific function call by passingcachier__skip_cache=Trueto the function call. The cache will neither be checked nor updated with the new return value.@cachier()defsum(first_num,second_num):returnfirst_num+second_numdefmain():print(sum(5,3,cachier__skip_cache=True))Overwrite CacheYou can havecachieroverwrite an existing cache entry - if one exists - for a specific function call by passingcachier__overwrite_cache=Trueto the function call. The cache will not be checked but will be updated with the new return value.Verbose Cache CallYou can havecachierprint out a detailed explanation of the logic of a specific call by passingcachier__verbose=Trueto the function call. This can be useful if you are not sure why a certain function result is, or is not, returned.CacheNoneValuesBy default,cachierdoes not cacheNonevalues. You can override this behaviour by passingallow_none=Trueto the function call.Cachier CoresPickle CoreThe default core for Cachier is pickle based, meaning each function will store its cache is a separate pickle file in the~/.cachierdirectory. Naturally, this kind of cache is both machine-specific and user-specific.You can configurecachierto use another directory by providing thecache_dirparameter with the path to that directory:@cachier(cache_dir='~/.temp/.cache')You can slightly optimise pickle-based caching if you know your code will only be used in a single thread environment by setting:@cachier(pickle_reload=False)This will prevent reading the cache file on each cache read, speeding things up a bit, while also nullifying inter-thread functionality (the code is still thread safe, but different threads will have different versions of the cache at times, and will sometime make unnecessary function calls).Setting the optional argumentseparate_filestoTruewill cause the cache to be stored in several files: A file per argument set, per function. This can help if your per-function cache files become too large.fromcachierimportcachier@cachier(separate_files=True)deffoo(arg1,arg2):"""Your function now has a persistent cache mapped by argument values, split across several files, per argument set"""return{'arg1':arg1,'arg2':arg2}You can get the fully qualified path to the directory of cache files used bycachier(~/.cachierby default) by calling thecache_dpath()function:>>>foo.cache_dpath()"/home/bigus/.cachier/"MongoDB CoreYou can set a MongoDB-based cache by assigningmongetterwith a callable that returns apymongo.Collectionobject with writing permissions:frompymongoimportMongoClientdefmy_mongetter():client=MongoClient(get_cachier_db_auth_uri())db_obj=client['cachier_db']if'someapp_cachier_db'notindb_obj.list_collection_names():db_obj.create_collection('someapp_cachier_db')returndb_obj['someapp_cachier_db']@cachier(mongetter=my_mongetter)This allows you to have a cross-machine, albeit slower, cache. This functionality requires that the installation of thepymongopython package.In certain cases the MongoDB backend might leave a deadlock behind, blocking all subsequent requests from being processed. If you encounter this issue, supply thewait_for_calc_timeoutwith a reasonable number of seconds; calls will then wait at most this number of seconds before triggering a recalculation.@cachier(mongetter=False,wait_for_calc_timeout=2)Memory CoreYou can set an in-memory cache by assigning thebackendparameter with'memory':@cachier(backend='memory')Note, however, thatcachier’s in-memory core is simple, and has no monitoring or cap on cache size, and can thus lead to memory errors on large return values - it is mainly intended to be used with future multi-core functionality. As a rule, Python’s built-inlru_cacheis a much better stand-alone solution.ContributingCurrent maintainers are Shay Palachy Affek (shay.palachy@gmail.com,@shaypal5) and Judson Neer (@lordjabez); You are more than welcome to approach them for help. Contributions are very welcomed! :)Installing for developmentClone:gitclonegit@github.com:python-cachier/cachier.gitInstall in development mode with test dependencies:cdcachierpipinstall-e.-rtests/requirements.txtRunning the testsTo run the tests, call thepytestcommand in the repository’s root, or:python-mpytestTo run only MongoDB core related tests, use:pytest-mmongoTo run only memory core related tests, use:pytest-mmemoryTo run all tests EXCEPT MongoDB core related tests, use:pytest-m"not mongo"To run all tests EXCEPT memory core AND MongoDB core related tests, use:pytest-m"not (mongo or memory)"Running MongoDB tests against a live MongoDB instanceNote to developers:By default, all MongoDB tests are run against a mocked MongoDB instance, provided by thepymongo_inmemorypackage. To run them against a live MongoDB instance, theCACHIER_TEST_VS_DOCKERIZED_MONGOenvironment variable is set toTruein thetestenvironment of this repository (and additional environment variables are populated with the appropriate credentials), used by the GitHub Action running tests on every commit and pull request.Contributors are not expected to run these tests against a live MongoDB instance when developing, as credentials for the testing instance used will NOT be shared, but rather use the testing against the in-memory MongoDB instance as a good proxy.HOWEVER, the tests run against a live MongoDB instance when you submit a PR are the determining tests for deciding whether your code functions correctly against MongoDB.Adding documentationThis project is documented using thenumpy docstring conventions, which were chosen as they are perhaps the most widely-spread conventions that are both supported by common tools such as Sphinx and result in human-readable docstrings (in my personal opinion, of course). When documenting code you add to this project, please followthese conventions.Additionally, if you update thisREADME.rstfile, usepython setup.py checkdocsto validate it compiles.CreditsCreated byShay Palachy Affek(shay.palachy@gmail.com), which currently assists in maintenance.Current lead developer/contributor:Jirka Borovec(@Bordaon GitHub).Other major contributors:Jirka Borovec- Arg order independence, args-to-kwargs for less unique keys and numerous development and CI contributions.Judson Neer- Precaching, method caching support and numerous improvements and bugfixes.cthoyt- Base memory core implementation.amarczew- Thehash_funckwarg.non-senses- Thewait_for_calc_timeoutkwarg.Elad Rapaport- Multi-file Pickle core, a.k.aseparate_files(released onv1.5.3).John Didion- Support for pickle-based caching for cases where two identically-named methods of different classes are defined in the same module.Notable bugfixers:MichaelRazum.Eric Ma- The iNotify bugfix (released onv1.5.3).Ofir- The iNotify bugfix (released onv1.5.3).