Package: easy-cache
Easy caching decoratorsThis package is intended to simplify caching and invalidation process in python-based (primarily) web applications. It's possible to cache execution results of functions;instance,classandstaticmethods; properties. Cache keys may be constructed in various different ways and may depend on any number of parameters.The package supports tag-based cache invalidation and better works with Django, however any other frameworks can be used – see examples below.The main idea of this package: you don't need to touch any existing function code to cache its execution results.RequirementsLibrary was tested in the following environments:Python 3.7, 3.8, 3.9, 3.10Django >=2.0.0Feel free to try it in yours, but it's not guaranteed it will work. Submit an issue if you think it should.Installationpipinstalleasy_cacheIntroductionDifferent ways to cache somethingImagine you have a time consuming function and you need to cache an execution results, the classic way to achieve this is the next one:# classic wayfromdjango.core.cacheimportcachedeftime_consuming_operation(n):"""Calculate sum of number from 1 to provided n"""cache_key='time_consuming_operation_{}'.format(n)result=cache.get(cache_key,None)ifresultisNone:# not found in cacheresult=sum(range(n+1))# cache result for one hourcache.set(cache_key,result,3600)returnresultdefinvalidate_cache(n):cache.delete('time_consuming_operation_{}'.format(n))Well, we had to add annoying boilerplate code to achieve this.
Now let's take a look howeasy_cachecan avoid the problem and simplify the code:# easy wayfromeasy_cacheimportecached@ecached('time_consuming_operation_{n}',3600)deftime_consuming_operation(n):returnsum(range(n+1))definvalidate_cache(n):time_consuming_operation.invalidate_cache_by_key(n)As we can see the function code left clear.
Heart of the package is two decorators with the similar parameters:ecachedShould be used to decorate any callable and cache returned result.Parameters:cache_key– cache key generator, default value isNoneso the key will be composed automatically based on a function name, namespace and passed parameters. Also the following types are supported:string– may containPython advanced string formatting syntax, a given value will be formatted with a dict of parameters passed to decorated function, see examples below.sequence of strings– each string must be function parameter name.callable– is used to generate cache key, decorated function parameters will be passed to this callable and returned value will be used as a cache key. Also one additional signature is available:callable(meta), wheremetais a dict-like object with some additional attributes – see below.timeout– value will be cached with provided timeout, basically it should be number of seconds, however it depends on cache backend type. Default value isDEFAULT_VALUE– internal constant means that actually no value is provided to cache backend and thus backend should decide what timeout to use. Callable is also supported.tags– sequence of strings or callable. Should provide or return list of tags added to cached value so cache may be invalidated later with any tag name. Tag may support advanced string formatting syntax. Seecache_keydocs and examples for more details.prefix– this parameter works both: as regular tag and also as cache key prefix, as usual advanced string formatting and callable are supported here.cache_alias– cache backend alias name, it can also beDjango cache backend alias  name.cache_instance– cache backend instance may be provided directly via this parameter.ecached_propertyShould be used to create so-called cached properties, has signature exactly the same as forecached.Simple examplesCode examples is the best way to show the power of this package.Decorators can be simply used with default parameters onlyfromeasy_cacheimportecached,create_cache_key# default parameters# cache key will be generated automatically:## <__module__>.<__class__>.<function name> + function parameters converted to strings,## so be careful when using complex objects, it's# better to write custom cache key generator in such cases.## timeout will be default for specified cache backend# "default" cache backend will be used if you use Django@ecached()deftime_consuming_operation(*args,**kwargs):pass# simple static cache key and cache timeout 100 seconds@ecached('time_consuming_operation',100)deftime_consuming_operation():pass# cache key with advanced string formatting syntax@ecached('my_key:{b}:{d}:{c}')deftime_consuming_operation(a,b,c=100,d='foo'):pass# or@ecached('key:{kwargs[param1]}:{kwargs[param2]}:{args[0]}')deftime_consuming_operation(*args,**kwargs):pass# use specific cache alias, see "caches framework" belowfromfunctoolsimportpartialmemcached=partial(ecached,cache_alias='memcached')# equivalent to cache_key='{a}:{b}'@memcached(['a','b'],timeout=600)deftime_consuming_operation(a,b,c='default'):passUsing custom cache key generators# working with parameters provided to cached function# cache key generator must have the same signature as decorated functionfromeasy_cacheimportcreate_cache_keydefcustom_cache_key(self,a,b,c,d):returncreate_cache_key(self.id,a,d)# working with `meta` objectdefcustom_cache_key_meta(meta):return'{}:{}:{}'.format(meta['self'].id,meta['a'],meta['d'])# or equivalentfromeasy_cacheimportmeta_accepted@meta_accepteddefcustom_cache_key_meta(parameter_with_any_name):meta=parameter_with_any_namereturn'{}:{}:{}'.format(meta['self'].id,meta['a'],meta['d'])classA(object):id=1@ecached(custom_cache_key)deftime_consuming_operation(self,a,b,c=10,d=20):...@ecached(custom_cache_key_meta)deftime_consuming_operation(self,a,b,c=10,d=20):...How to cachestaticmethodandclassmethodcorrectly# ecached decorator always comes topmostclassB(object):# cache only for each different year@ecached(lambdastart_date:'get_list:{}'.format(start_date.year))@staticmethoddefget_list_by_date(start_date):...CONST='abc'@ecached('info_cache:{cls.CONST}',3600,cache_alias='redis_cache')@classmethoddefget_info(cls):...MetaCallable object descriptionMeta object has the following parameters:args– tuple with positional arguments provided to decorated functionkwargs– dictionary with keyword arguments provided to decorated functionreturned_value– value returned from decorated function, available only when meta object is handled intagsorprefixgenerators. You have to checkhas_returned_valueproperty before using this parameter:defgenerate_cache_key(meta):ifmeta.has_returned_value:# ... do something with meta.returned_value ...call_args- dictionary with all positional and keyword arguments provided
to decorated function, you may also access them via__getitem__dict interface, e. g.meta['param1'].function- decorated callablescope- object to which decorated callable is attached,Noneotherwise. Usually it's an instance or a class.Tags invalidation, refresh and cached propertiesTags-based cache invalidation allows you to invalidate several cache keys at once.Imagine you created a web-based book store and your users can mark a book as liked, so you need to maintain a list of liked books for every user but, an information about a book may contain a lot of different data, e.g. authors names, rating, availability in stock, some data from external services and so on.Some of this information can be calculated on runtime only so you decided to cache the list of liked books.But what if a book title was updated and we have to find all cache keys where this book is stored and invalidate them. Such task may be pretty complex to complete, however if you tagged all the necessary cache keys with a specific tag you will just need to invalidate the tag only and related cache keys will be invalidated "automatically".Here are more complex examples introducing Django models and effective tags usage.
Check code comments and doc-strings for detailed description.fromdjango.dbimportmodelsfromeasy_cacheimportecached,ecached_property,create_cache_keyclassBook(models.Model):title=models.CharField(max_length=250)def__unicode__(self):returnself.titleclassUser(models.Model):name=models.CharField(max_length=100)state=models.CharField(max_length=15,choices=(('active','active'),('deleted','deleted')),)friends=models.ManyToManyField('self',symmetrical=True)favorite_books=models.ManyToManyField('Book')def__unicode__(self):returnself.name@ecached('users_by_state:{state}',60,tags=['users_by_states'])@classmethoddefget_users_by_state(cls,state):"""Caches user list by provided state parameter: there will be separatecached value for every different state parameter, so we are having 2 differentcache keys:users_by_state:active – cached list of active usersusers_by_state:deleted – cached list of deleted usersNote that `ecached` decorator always comes topmost.To invalidate concrete cached state call the following methodwith the required `state`, e.g.:>>> User.get_users_by_state.invalidate_cache_by_key('active')... removes `users_by_state:active` cache keyor>>> User.get_users_by_state.invalidate_cache_by_key(state='deleted')... removes `users_by_state:deleted` cache keyIf you'd like to invalidate all caches for all states call:>>> User.get_users_by_state.invalidate_cache_by_tags('users_by_states')... removes both keys, since `users_by_states` tag attached to all of them,`invalidate_cache_by_tags` supports both string and list parameter types:>>> invalidate_cache_by_tags(['tag1', 'tag2', 'tag3'])To refresh concrete cached state call the following methodwith required `state`, e.g:>>> User.get_users_by_state.refresh_cache('active')... calls `get_users_by_state('active')` and saves returned value to cacheor>>> User.get_users_by_state.refresh_cache(state='deleted')"""returnlist(cls.objects.filter(state=state))@ecached_property('user_friends_count:{self.id}',timeout=3600)deffriends_count(self):"""Caches friends count of each user for 1 hour.To access cache invalidation functions for a property youhave to use class object instead of instance.Call the following method, to invalidate cache:>>> User.friends_count.invalidate_cache_by_key(user)... removes cache key `user_friends_count:{user.id}`or>>> type(self).friends_count.invalidate_cache_by_key(user)or>>> self.__class__.friends_count.invalidate_cache_by_key(user)Where `user` is desired User instance to invalidate friends count for.Call the following method, to refresh cached data:>>> User.friends_count.refresh_cache(user)... Updates `user.friends_count` in a cache.or>>> type(self).friends_count.refresh_cache(user)or>>> self.__class__.friends_count.refresh_cache(user)"""returnself.friends.count()@staticmethoddefget_books_tags(meta):"""Add one tag for every book in list of favorite books.So we will add a list of tags to cached favorite books list."""ifnotmeta.has_returned_value:return[]favorite_books=meta.returned_value# yes, it may occupy a lot of cache keysreturn[create_cache_key('book',book.pk)forbookinfavorite_books]@ecached('user_favorite_books:{self.id}',600,get_books_tags)defget_favorite_books(self):"""Caches list of related books by user id. So in code you will use:>>> favorite_books = request.user.get_favorite_books() # cached for userYou may want to invalidate this cache in two cases:1. User added new book to favorites:>>> User.get_favorite_books.invalidate_cache_by_key(user)or>>> User.get_favorite_books.invalidate_cache_by_key(self=user)or>>> from easy_cache import invalidate_cache_key, create_cache_key>>> invalidate_cache_key(create_cache_key('user_favorite_books', user.id))or>>> invalidate_cache_key('user_favorite_books:{}'.format(user.id))2. Some information about favorite book was changed, e.g. its title:>>> from easy_cache import invalidate_cache_tags, create_tag_cache_key>>> tag_cache_key = create_tag_cache_key('book', changed_book_id)>>> User.get_favorite_books.invalidate_cache_by_tags(tag_cache_key)or>>> invalidate_cache_tags(tag_cache_key)To refresh cached values use the following patterns:>>> User.get_favorite_books.refresh_cache(user)or>>> User.get_favorite_books.refresh_cache(self=user)"""returnself.favorite_books.filter(user=self)Prefix usageCommonlyprefixis used to invalidate all cache-keys in one namespace, e. g.:fromfunctoolsimportpartialclassShop(models.Model):single_shop_cache=partial(ecached,prefix='shop:{self.id}')@single_shop_cache('goods_list')defget_all_goods_list(self):return[...]@single_shop_cache('prices_list')defget_all_prices_list(self):return[...]# if you have `shop` object you are able to use the following invalidation# strategies:# Invalidate cached list of goods for concrete shopShop.get_all_goods_list.invalidate_cache_by_key(shop)# Refresh cached list of goods for concrete shopShop.get_all_goods_list.refresh_cache(shop)# Invalidate cached list of prices for concrete shopShop.get_all_prices_list.invalidate_cache_by_key(shop)# Refresh cached list of prices for concrete shopShop.get_all_prices_list.refresh_cache(shop)# Invalidate all cached items for concrete shopShop.get_all_goods_list.invalidate_cache_by_prefix(shop)# orShop.get_all_prices_list.invalidate_cache_by_prefix(shop)# orfromeasy_cacheimportinvalidate_cache_prefixinvalidate_cache_prefix('shop:{self.id}'.format(self=shop))Invalidation summaryThere are two ways to invalidate cache objects: use invalidation methods bound to decorated function and separate functions-invalidators.<decorated>.invalidate_cache_by_key(*args,**kwargs)<decorated>.invalidate_cache_by_tags(tags=(),*args,**kwargs)<decorated>.invalidate_cache_by_prefix(*args,**kwargs)# <decorated> should be used with a class instance if it is used in a class namespace:classA:id=1@ecached()defmethod(self):pass@ecached_property()defobj_property(self):pass@ecached_property('{self.id}:hello')defworld(self):return'<timeconsuming>'A.method.invalidate_cache_by_key()# orA().method.invalidate_cache_by_key()# only one variant is possible for a propertiesA.obj_property.invalidate_cache_by_key()# anditem=A()A.world.invalidate_cache_by_key(item)# andfromeasy_cacheimport(invalidate_cache_key,invalidate_cache_tags,invalidate_cache_prefix,create_cache_key,)# Note that `cache_instance` and `cache_alias` may be passed# to the following invalidatorsinvalidate_cache_key(cache_key)invalidate_cache_tags(tags)invalidate_cache_prefix(prefix)Heretagscan be a string (single tag) or a list of tags. Bound methods should be provided with parameters if they are used in cache key/tag/prefix:@ecached('key:{a}:value:{c}',tags=['tag:{a}'],prefix='pre:{b}',cache_alias='memcached')deftime_consuming_operation(a,b,c=100):passtime_consuming_operation.invalidate_cache_by_key(a=1,c=11)time_consuming_operation.invalidate_cache_by_tags(a=10)time_consuming_operation.invalidate_cache_by_prefix(b=2)# or using `create_cache_key` helperinvalidate_cache_key(create_cache_key('key',1,'value',11),cache_alias='memcached')invalidate_cache_tags(create_cache_key('tag',10),cache_alias='memcached')invalidate_cache_prefix('pre:{}'.format(2),cache_alias='memcached')Refresh summaryThere is one way to refresh cache objects: use refresh methods bound to decorated function.<decorated>.refresh_cache(*args,**kwargs)# <decorated> should be used with class instance if it is used in class namespace:classA:@ecached()defmethod(self):pass@ecached_property()defobj_property(self):passA.method.refresh_cache()A.obj_property.refresh_cache()Internal caches frameworkBe aware: internal cache framework instance is single threaded, so if you add new cache instance in a one thread it won't appear in another.Easy-cache uses build-in Django cache framework by default, so you can choose what cache storage to use on every decorated function, e.g.:# Django settingsCACHES={'local_memory':{'BACKEND':'django.core.cache.backends.locmem.LocMemCache','LOCATION':'locmem','KEY_PREFIX':'custom_prefix',},'memcached':{'BACKEND':'django.core.cache.backends.memcached.PyMemcacheCache','LOCATION':'127.0.0.1:11211','KEY_PREFIX':'memcached',}}# then in somewhere code@ecached(...,cache_alias='memcached')# or@ecached(...,cache_alias='local_memory')# or evenfromdjango.core.cacheimportcachesanother_cache=caches['another_cache']@ecached(...,cache_instance=another_cache)However if you don't use Django, there is cache framework built into easy-cache package, it can be used in the same fashion as Django caches:# Custom cache instance class must implement AbstractCacheInstance interface:fromeasy_cache.abcimportAbstractCacheInstancefromeasy_cache.coreimportDEFAULT_TIMEOUT,NOT_FOUNDclassCustomCache(AbstractCacheInstance):defget(self,key,default=NOT_FOUND):...defget_many(self,keys):...defset(self,key,value,timeout=DEFAULT_TIMEOUT):...defset_many(self,data_dict,timeout=DEFAULT_TIMEOUT):...defdelete(self,key):...fromeasy_cacheimportcachescustom_cache=CustomCache()caches['new_cache']=custom_cachecaches.set_default(CustomCacheDefault())# and then@ecached(...,cache_alias='new_cache')# or@ecached(...,cache_instance=custom_cache)# will use `default` alias@ecached(...)There is already implemented redis cache instance class, based onredis-py client:fromredisimportStrictRedisfromeasy_cache.contrib.redis_cacheimportRedisCacheInstancefromeasy_cacheimportcachesredis_cache=RedisCacheInstance(StrictRedis(host='...',port='...'))caches.set_default(redis_cache)# will use `default` alias@ecached(...)Dynamic timeout exampleYou may need to provide cache timeout dynamically depending on function parameters:defdynamic_timeout(group):ifgroup=='admins':timeout=10else:timeout=100returntimeout@ecached('key:{group}',timeout=dynamic_timeout)defget_users_by_group(group):...Development and contributionLive instances of Redis and Memcached are required for few tests to pass, so it's recommended to use docker/docker-compose to setup the necessary environment:docker-composeup-d# to enable debug logs# export EASY_CACHE_DEBUG="yes"# install package locallypipinstall-e.[tests]# run tests with pytest or toxpytest
toxPerformance and overheadBenchmarking may be executed withtoxcommand and it shows that decorators give about 4% of overhead in worst case and about 1-2% overhead on the average.If you don't use tags or prefix you will get one cache request forgetand one request forsetif result not found in cache, otherwise two consecutive requests will be made:getandget_manyto receive actual value from cache and validate its tags (prefix). Then oneset_manyrequest will be performed to save a data to cache storage.