Package: toolcache
toolcachetoolcachemakes it simple to create and configure caches in pythonFeaturessave caches to memory or to diskmemoize functions, instance methods,@classmethods, and@staticmethodscontrol cache size with ttl and eviction policies like lru / fifo / lfuuse thread safety, process safety, or no safety (default = thread safety)use custom hash functionstrack cache usage statisticsInstallpip install toolcacheContentsExample UsageReferenceCache TypesCache CreationCache ConfigurationCache DecoratorsCache MethodsFrequently Asked QuestionsExample UsageCreating Cachesimporttoolcache# memoize function with memory cache@toolcache.cache('memory')deff(a,b,c):returna*b*c# memoize function with disk cache, stored in a tempdir@toolcache.cache('disk')deff(a,b,c):returna*b*c# memoize function with disk cache, stored in a persistent dir@toolcache.cache('disk',cache_dir='/path/to/cache/dir')deff(a,b,c):returna*b*c# remove cache entries once they reach a specific age@toolcache.cache('disk',ttl='24 hours')deff(a,b,c):returna*b*c# remove cache entries once cache reaches a specific size@toolcache.cache('disk',max_size=3,max_size_policy='fifo')deff(a,b,c):returna*b*c# specify which args are used to create unique hash of inputs@toolcache.cache('disk',hash_args=['a','b'])deff(a,b,c):returna*b*c# create standalone cachestandalone_cache=toolcache.MemoryCache()Using Caches# get cache sizeprint(f.cache.get_cache_size())>4# track cache usage statisticsprint(f.cache.stats)>{'n_checks':6,>'n_deletes':2,>'n_hashes':8,>'n_hits':2,>'n_loads':1,>'n_misses':4,>'n_saves':3,>'n_size_evictions':0,>'n_ttl_evictions':0}# clear cachef.cache.delete_all_entries()More ExamplesConfigure HashingConfigure Disk CachesUse Cache Eviction PoliciesMonitor Cache UsageCreate Standalone CachesDefine Custom CachetypesCache ReferenceCache Typestoolcacheincludes 3 cache types that each inherit from abstract cache classBaseCache:cachetypedescriptionuse caseMemoryCachecache that saves each entry as key-value pair in adictspeedDiskCachecache that saves each entry as a file to diskpersistence, or large data that does not fit in memoryNullCachecache that does not save any entriesprogrammatically disabling cacheCache CreationCaches can be created in two ways:decorating a function with@toolcache.cache(cachetype)wherecachetypeis'memory','disk','null', or a class inheriting fromBaseCachecreating a standalone cache by instantiating a class that inherits fromBaseCacheCache ConfigurationThe configuration options listed below can be passed totoolcache.cache()or passed to a standalone cache during initialization.General Configthese configuration options are available to every cacheargdescriptionexample valuedefault behaviorsafetystrname of concurrency safety level, one of'thread','process', orNone'thread''thread'verboseboolof whether to print info whenever saving to or loading from cacheFalseFalsecache_nameboolof whether to print info whenever saving to or loading from cache'important_cache'use decorated function name, or uuid for  a standalone cacheHash Configargdescriptionexample valuedefault behaviorf_hashcustom function for computing hashlambda x: hash(x)toolcache. compute_hash_json()normalize_hash_inputsbool of whether to normalize function calls so that for a functionfwith argsaandb, the callsf(1, 2)andf(a=1, b=2)are equivalentFalseFalsehash_include_argslistofstrnames of arguments used to compute hash['arg1', 'arg2']include all argshash_exclude_argslistofstrnames of arguments excluded from hash['arg3', 'arg4']exclude no argsEviction Configargdescriptionexample valuedefault behaviorttlTimelengthof time-to-live maximum age for entries in cache'1000s'no max agemax_sizeintof max size of cache size1000no max sizemax_size_policystrname of eviction policy to use whenmax_sizeis exceeded, one of'lru','fifo', or'lfu''fifo'`'lru''Statistic Tracking Configargdescriptionexample valuedefault behaviortrack_basic_statsboolof whether to track basic usage statsFalseFalsetrack_detailed_statsboolof whether to track creations and accessesFalseFalsetrack_creation_timesboolof whether to track creation timesFalsetrack only ifttlis notNoneormax_size_policy == 'fifo'track_access_timesboolof whether to track access timesFalsetrack only ifmax_size_policy == 'lru'track_access_countsboolof whether to track access countsFalsetrack only ifmax_size_policy == 'lfu'DiskCache-specific Configargdescriptionexample valuedefault behaviorcache_dirstrof directory path to store cache data'/path/to/cache_dir'create atmpdirfile_formatstrof file format to use for cache data, either'pickle'or'json''json''pickle'f_disk_savecustom function for saving data to disk, function should takeentry_pathandentry_dataas argumentsf_savesave as picklef_disk_loadcustom function for load data from disk, function should takeentry_pathas an argumentf_loadload as pickleCache DecoratorsWhen usingtoolcache.cache()to decorate a function, one should consider 1) how function inputs will be hashed, 2) what attributes will be added to the function, and 3) what arguments might be added to the function.Hashing Function InputsTo save a function input-output pair within a cache, a unique hash must be taken of the inputs.Under the default hash configuration, each input arg should either be json-serializable or be a hashable object (i.e. it implements a__hash__()method). By defaulttoolcacheusesorjsonto create these hashes quickly.If function inputs do not satisfy these criteria, one or more of the cache config parameters should be used:parameterdescriptionexamplef_hashprovide a custom hash function that takes the same args and kwargs as the decorated function@toolcache.cache(..., f_hash=f_custom_hash)hash_include_argsspecifylistof arg names that should be used to compute hash@toolcache.cache(..., hash_include_args=['arg1', 'arg2'])hash_exclude_argsspecifylistof arg names that should not be used to compute hash@toolcache.cache(..., hash_exclude_args=['arg3', 'arg4'])toolcache.cache()also works on functions that have*argsor**kwargsfor inputsDecorated Function ArgsEvery time the decorated function is called, it can use the following keyword args to control cache behavior.kwargdescriptiondefaultexamplecache_saveboolof whether to save output to cacheTruef(..., cache_save=False)will not save output to cachecache_loadboolof whether to attempt to load entry from cacheTruef(..., cache_load=False)will not attempt to load entry from cachecache_verboseboolof whether to print info about loading from or saving to cacheTruef(..., cache_load=False)will not attempt to load entry from cacheYou can avoid adding these args to the decorated function by using@toolcache.cache(..., add_cache_args=False).Decorated Function AttributesThe original decorated function can be acessed asf.__wrapped__.The cache instance associated with a decorated functionf()can be accessed usingf.cache.Cache MethodsThese methods are available on every cache instance:methoddescriptioncompute_entry_hash()compute hash of entrysave_entry()save entry data to cacheexists_in_cache()returnboolof whether entry exists in cacheload_entry()load entry data from cacheget_cache_size()returnintnumber of items in cachedelete_entry()remove entry from cachedelete_all_entries()delete all entries from cacheFrequently Asked QuestionsHow is the performance? What is the overhead for using a cache decorator?To maximize cache performance, one can disable input name normalization (normalize_hash_inputs=False), statistic tracking (track_basic_stats=Falseandtrack_detailed_stats=False), and thread safety (safety=None).On a somewhat modern machine with the above settings, thetoolcache.cache()decorator adds about 3 μs to each function call, whereas running a simple function with no cache decorator takes about 50 ns per function call. Using a disk cache instead of a memory cache adds about 25 μs per function call. To truly know whethertoolcacheis fast enough for your application you may need to run your own benchmarks.How doestoolcacherelate to other similar projects?A large motivation for developingtoolcachewas being able to manage memory-based and disk-based caches with a unified interface and feature set.toolcacheis currently the only python package to offer this functionality.There exist many other python packages for caching and memoization.cacheoutandpython-memoizationboth provide in-memory caches with many features. Compared totoolcachethese libraries provide a wider variety of cache eviction policies and other interesting features.python-diskcacheprovides a feature-rich disk-based cache with Django integration and extensive benchmark comparisons to other solutions.