memorize: A caching package with options for timed caching and caching aware rate limiting

Installation

To install memorize, simply use pip:

$ pip install memorize

or install directly from source to include latest changes:

$ pip install git+https://github.com/saporitigianni/memorize.git

or clone and then install:

$ git clone https://github.com/saporitigianni/memorize.git
$ cd memorize
$ python3 setup.py install

Usage

This class extends the functools.lru_cache functionality to add timed caching and caching aware rate limiting (e.g. if call results are returned from the cache then that particular call does not affect the rate limit)

Constraints:

• Since a dictionary is used to cache results, the positional and keyword arguments to the function must be hashable (NOT lists, dicts, sets, or any other object that does not define hash())
• It is very important to use the parenthesis even if empty: @memorize() NOT @memorize
• When rate limiting, both the calls and period arguments must be provided otherwise an error is raised

Default Settings:

• timeout = None (can be int or float)
• maxsize = None (can be int)
• typed = False (can be True)
• calls = None (can be int)
• period = None (can be int or float)
• aware = False (can be True)

from memorize import memorize

# If you want to use all default settings
@memorize()
def fib(n):
    if n < 2:
        return n
    else:
        return fib(n-2) + fib(n-1)

# With memorization fib(20) will be run 21 times instead of 21891 times
# without memorization
fib(20)

# If you want to cache a maximum of 128 calls, cached by different types,
# each for 10 seconds use:
@memorize(timeout=10, maxsize=128, typed=True)

# If you want to implement caching aware rate limiting then use the following:
# This will limit to no more than 10 calls for every 5 second period and if a
# result is returned from the cache it does not count towards the 10 calls.
@memorize(calls=10, period=5, aware=True)

Contributing

Please read the CONTRIBUTING document before making changes that you would like adopted in the code.

Code of Conduct

Everyone interacting in the memorize project's codebase, issue trackers, chat rooms, and mailing lists is expected to follow the PyPA Code of Conduct.