Skip to main content

A simple caching utility in Python 3

Project description

A simple caching utility in Python 3.

simple_cache uses the pickle module to write any key : value pairs to a file on disk.

It was written as an easy way to cache http requests for local use. It can possibly be used for caching any data, as long as the key s are hashable and the value s are pickleable.

It also provides a decorator to cache function calls directly.


Only standard libraries are used, so there are no dependencies.


pip install simple_cache

Or if you like, you can just download the file and import it locally.


Each cache file contains a single dictionary, acting as the namespace for that cache. Within the file, you can set and retrieve any key : value pairs as needed.

When setting a key, you must give a ttl value, or time to live, in seconds. This value determines the amount of time that value will be considered valid. After that, the value is considered expired, and will not be returned.

Calls to a non-existent cache file, a non-existent key, or an expired key all return None.

You can set a key with a new value before or after it expires.

Whenever you ask the cache for a value, and it happens to be expired, the item is deleted from the file. You can also manually ask the cache file at any time, to prune all currently expired items.


import simple_cache

Using the decorator format:

Using the same cache file for multiple functions with a decorator might cause problems. The decorator uses the *args, **kwargs of the function as a key, so calling to different functions with the same arguments will cause a clash.

You can specify a custom filename (and ttl) with the decorator format, overriding the default values.

Please note that the decorator format only supports args and kwargs with immutable types. If one of your arguments is mutable (e.g. a list, or a dictionary), the decorator won’t work.

@simple_cache.cache_it()    # uses defaults: filename = "simple.cache", ttl = 3600
def some_function(*args, **kwargs):
    # body
    return value
@simple_cache.cache_it(filename="some_function.cache", ttl=120)
def some_function(*args, **kwargs):
    # body
    return value

Using the module functions:

Setting a key and value:

simple_cache.save_key(filename, key, value, ttl)

Retrieving a value:

simple_cache.load_key(filename, key)

Pruning all expired items in a file:


Loading the whole cache dictionary from a file (possibly for debugging or introspection):


Writing a whole dictionary to a file, overwriting any previous data in the file (possibly for initalizing a cache by batch writing multiple items):

simple_cache.write_cache(filename, cache)

filename is a string containing a valid filename

key is any hashable type, and must be unique within each cache file (otherwise will overwrite)

value is any Python type supported by the pickle module

ttl is an integer or float, denoting the number of seconds that the item will remain valid before it expires

cache is a dictionary containing the key:value pairs


simple_cache is open sourced under GPLv3.

Project details

Release history Release notifications

This version
History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date (5.9 kB) Copy SHA256 hash SHA256 Source None Mar 28, 2013

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page