Package: memoization
python-memoizationA powerful caching library for Python, with TTL support and multiple algorithm options.If you like this work, pleasestarit on GitHub.Why choose this library?Perhaps you know aboutfunctools.lru_cachein Python 3, and you may be wondering why we are reinventing the wheel.Well, actually not. This lib is based onfunctools. Please find below the comparison withlru_cache.Featuresfunctools.lru_cachememoizationConfigurable max size✔️✔️Thread safety✔️✔️Flexible argument typing (typed & untyped)✔️Always typedCache statistics✔️✔️LRU (Least Recently Used) as caching algorithm✔️✔️LFU (Least Frequently Used) as caching algorithmNo support✔️FIFO (First In First Out) as caching algorithmNo support✔️Extensibility for new caching algorithmsNo support✔️TTL (Time-To-Live) supportNo support✔️Support for unhashable arguments (dict, list, etc.)No support✔️Custom cache keysNo support✔️On-demand partial cache clearingNo support✔️Iterating through the cacheNo support✔️Python version3.2+3.4+memoizationsolves some drawbacks offunctools.lru_cache:lru_cachedoes not supportunhashable types, which means function arguments cannot contain dict or list.>>>fromfunctoolsimportlru_cache>>>@lru_cache()...deff(x):returnx...>>>f([1,2])# unsupportedTraceback(mostrecentcalllast):File"<stdin>",line1,in<module>TypeError:unhashabletype:'list'lru_cacheis vulnerable tohash collision attackand can be hacked or compromised. Using this technique, attackers can make your programunexpectedly slowby
feeding the cached function with certain cleverly designed inputs. However, inmemoization, caching is always
typed, which meansf(3)andf(3.0)will be treated as different calls and cached separately. Also,
you can build your own cache key with a unique hashing strategy. These measuresprevents the attackfrom
happening (or at least makes it a lot harder).>>>hash((1,))3430019387558>>>hash(3430019387558.0)# two different arguments with an identical hash value3430019387558Unlikelru_cache,memoizationis designed to be highly extensible, which make it easy for developers to add and integrateany caching algorithms(beyond FIFO, LRU and LFU) into this library. SeeContributing Guidancefor further detail.Installationpipinstall-Umemoization1-Minute Tutorialfrommemoizationimportcached@cacheddeffunc(arg):...# do something slowSimple enough - the results offunc()are cached.
Repetitive calls tofunc()with the same arguments runfunc()only once, enhancing performance.:warning:WARNING:for functions with unhashable arguments, the default setting may not enablememoizationto work properly. Seecustom cache keyssection below for details.15-Minute TutorialYou will learn about the advanced features in the following tutorial, which enable you to customizememoization.Configurable options includettl,max_size,algorithm,thread_safe,order_independentandcustom_key_maker.TTL (Time-To-Live)@cached(ttl=5)# the cache expires after 5 secondsdefexpensive_db_query(user_id):...For impure functions, TTL (in second) will be a solution. This will be useful when the function returns resources that is valid only for a short time, e.g. fetching something from databases.Limited cache capacity@cached(max_size=128)# the cache holds no more than 128 itemsdefget_a_very_large_object(filename):...By default, if you don't specifymax_size, the cache can hold unlimited number of items.
When the cache is fully occupied, the former data will be overwritten by a certain algorithm described below.Choosing your caching algorithmfrommemoizationimportcached,CachingAlgorithmFlag@cached(max_size=128,algorithm=CachingAlgorithmFlag.LFU)# the cache overwrites items using the LFU algorithmdeffunc(arg):...Possible values foralgorithmare:CachingAlgorithmFlag.LRU:Least Recently Used(default)CachingAlgorithmFlag.LFU:Least Frequently UsedCachingAlgorithmFlag.FIFO:First In First OutThis option is valid only when amax_sizeis explicitly specified.Thread safe?@cached(thread_safe=False)deffunc(arg):...thread_safeisTrueby default. Setting it toFalseenhances performance.Order-independent cache keyBy default, the following function calls will be treated differently and cached twice, which means the cache misses at the second call.func(a=1,b=1)func(b=1,a=1)You can avoid this behavior by passing anorder_independentargument to the decorator, although it will slow down the performance a little bit.@cached(order_independent=True)deffunc(**kwargs):...Custom cache keysPrior to memorize your function inputs and outputs (i.e. putting them into a cache),memoizationneeds to
build acache keyusing the inputs, so that the outputs can be retrieved later.By default,memoizationtries to combine all your function
arguments and calculate its hash value usinghash(). If it turns out that parts of your arguments are
unhashable,memoizationwill fall back to turning them into a string usingstr(). This behavior relies
on the assumption that the string exactly represents the internal state of the arguments, which is true for
built-in types.However, this is not true for all objects.If you pass objects which are
instances of non-built-in classes, sometimes you will need to override the default key-making procedure,
because thestr()function on these objects may not hold the correct information about their states.Here are some suggestions.Implementations of a valid key maker:MUST be a function with the same signature as the cached function.MUST produce unique keys, which means two sets of different arguments always map to two different keys.MUST produce hashable keys, and a key is comparable with another key (memoizationonly needs to check for their equality).should compute keys efficiently and produce small objects as keys.Example:defget_employee_id(employee):returnemployee.id# returns a string or a integer@cached(custom_key_maker=get_employee_id)defcalculate_performance(employee):...Note that writing a robust key maker function can be challenging in some situations. If you find it difficult,
feel free to ask for help by submitting anissue.Knowing how well the cache is behaving>>>@cached...deff(x):returnx...>>>f.cache_info()CacheInfo(hits=0,misses=0,current_size=0,max_size=None,algorithm=<CachingAlgorithmFlag.LRU:2>,ttl=None,thread_safe=True,order_independent=False,use_custom_key=False)Withcache_info, you can retrieve the number ofhitsandmissesof the cache, and other information indicating the caching status.hits: the number of cache hitsmisses: the number of cache missescurrent_size: the number of items that were cachedmax_size: the maximum number of items that can be cached (user-specified)algorithm: caching algorithm (user-specified)ttl: Time-To-Live value (user-specified)thread_safe: whether the cache is thread safe (user-specified)order_independent: whether the cache is kwarg-order-independent (user-specified)use_custom_key: whether a custom key maker is usedOther APIsAccess the original undecorated functionfbyf.__wrapped__.Clear the cache byf.cache_clear().Check whether the cache is empty byf.cache_is_empty().Check whether the cache is full byf.cache_is_full().DisableSyntaxWarningbymemoization.suppress_warnings().Advanced API ReferencesDetailsChecking whether the cache contains somethingcache_contains_argument(function_arguments, alive_only)Return True if the cache contains a cached item with the specified function call arguments

:param function_arguments:  Can be a list, a tuple or a dict.
                            - Full arguments: use a list to represent both positional arguments and keyword
                              arguments. The list contains two elements, a tuple (positional arguments) and
                              a dict (keyword arguments). For example,
                                f(1, 2, 3, a=4, b=5, c=6)
                              can be represented by:
                                [(1, 2, 3), {'a': 4, 'b': 5, 'c': 6}]
                            - Positional arguments only: when the arguments does not include keyword arguments,
                              a tuple can be used to represent positional arguments. For example,
                                f(1, 2, 3)
                              can be represented by:
                                (1, 2, 3)
                            - Keyword arguments only: when the arguments does not include positional arguments,
                              a dict can be used to represent keyword arguments. For example,
                                f(a=4, b=5, c=6)
                              can be represented by:
                                {'a': 4, 'b': 5, 'c': 6}

:param alive_only:          Whether to check alive cache item only (default to True).

:return:                    True if the desired cached item is present, False otherwise.cache_contains_result(return_value, alive_only)Return True if the cache contains a cache item with the specified user function return value. O(n) time
complexity.

:param return_value:        A return value coming from the user function.

:param alive_only:          Whether to check alive cache item only (default to True).

:return:                    True if the desired cached item is present, False otherwise.Iterating through the cachecache_arguments()Get user function arguments of all alive cache elements

see also: cache_items()

Example:
   @cached
   def f(a, b, c, d):
       ...
   f(1, 2, c=3, d=4)
   for argument in f.cache_arguments():
       print(argument)  # ((1, 2), {'c': 3, 'd': 4})

:return: an iterable which iterates through a list of a tuple containing a tuple (positional arguments) and
        a dict (keyword arguments)cache_results()Get user function return values of all alive cache elements

see also: cache_items()

Example:
   @cached
   def f(a):
       return a
   f('hello')
   for result in f.cache_results():
       print(result)  # 'hello'

:return: an iterable which iterates through a list of user function result (of any type)cache_items()Get cache items, i.e. entries of all alive cache elements, in the form of (argument, result).

argument: a tuple containing a tuple (positional arguments) and a dict (keyword arguments).
result: a user function return value of any type.

see also: cache_arguments(), cache_results().

Example:
   @cached
   def f(a, b, c, d):
       return 'the answer is ' + str(a)
   f(1, 2, c=3, d=4)
   for argument, result in f.cache_items():
       print(argument)  # ((1, 2), {'c': 3, 'd': 4})
       print(result)    # 'the answer is 1'

:return: an iterable which iterates through a list of (argument, result) entriescache_for_each()Perform the given action for each cache element in an order determined by the algorithm until all
elements have been processed or the action throws an error

:param consumer:           an action function to process the cache elements. Must have 3 arguments:
                             def consumer(user_function_arguments, user_function_result, is_alive): ...
                           user_function_arguments is a tuple holding arguments in the form of (args, kwargs).
                             args is a tuple holding positional arguments.
                             kwargs is a dict holding keyword arguments.
                             for example, for a function: foo(a, b, c, d), calling it by: foo(1, 2, c=3, d=4)
                             user_function_arguments == ((1, 2), {'c': 3, 'd': 4})
                           user_function_result is a return value coming from the user function.
                           is_alive is a boolean value indicating whether the cache is still alive
                           (if a TTL is given).Removing something from the cachecache_clear()Clear the cache and its statistics informationcache_remove_if(predicate)Remove all cache elements that satisfy the given predicate

:param predicate:           a predicate function to judge whether the cache elements should be removed. Must
                            have 3 arguments, and returns True or False:
                              def consumer(user_function_arguments, user_function_result, is_alive): ...
                            user_function_arguments is a tuple holding arguments in the form of (args, kwargs).
                              args is a tuple holding positional arguments.
                              kwargs is a dict holding keyword arguments.
                              for example, for a function: foo(a, b, c, d), calling it by: foo(1, 2, c=3, d=4)
                              user_function_arguments == ((1, 2), {'c': 3, 'd': 4})
                            user_function_result is a return value coming from the user function.
                            is_alive is a boolean value indicating whether the cache is still alive
                            (if a TTL is given).

:return:                    True if at least one element is removed, False otherwise.Q&AQ: There are duplicated code inmemoizationand most of them can be eliminated by using another level of
abstraction (e.g. classes and multiple inheritance). Why not refactor?A: We would like to keep the code in a proper level of abstraction. However, these abstractions make it run slower.
As this is a caching library focusing on speed, we have to give up some elegance for better performance. Refactoring
is our future work.Q: I have submitted an issue and not received a reply for a long time. Anyone can help me?A: Sorry! We are not working full-time, but working voluntarily on this project, so you might experience some delay.
We appreciate your patience.ContributingThis project welcomes contributions from anyone.Read Contributing Guidancefirst.Submit bugsand help us verify fixes.Submit pull requestsfor bug fixes and features and discuss existing proposals. Please make sure that your PR passes the tests intest.py.See contributorsof this project.LicenseThe MIT License