API

Jobs

The main class is cacheback.base.Job. The methods that are intended to be called from client code are:

class cacheback.base.Job

A cached read job.

This is the core class for the package which is intended to be subclassed to allow the caching behaviour to be customised.

delete(*raw_args, **raw_kwargs)

Remove an item from the cache

get(*raw_args, **raw_kwargs)

Return the data for this function (using the cache if possible).

This method is not intended to be overidden

invalidate(*raw_args, **raw_kwargs)

Mark a cached item invalid and trigger an asynchronous job to refresh the cache

It has some class properties than can be used to configure simple behaviour:

class cacheback.base.Job

A cached read job.

This is the core class for the package which is intended to be subclassed to allow the caching behaviour to be customised.

cache_alias = None

Secifies which cache to use from your CACHES setting. It defaults to default.

fetch_on_miss = True

Whether to perform a synchronous refresh when a result is missing from the cache. Default behaviour is to do a synchronous fetch when the cache is empty. Stale results are generally ok, but not no results.

fetch_on_stale_threshold = None

Whether to perform a synchronous refresh when a result is in the cache but stale from. Default behaviour is never to do a synchronous fetch but there will be times when an item is _too_ stale to be returned.

lifetime = 600

Default cache lifetime is 10 minutes. After this time, the result will be considered stale and requests will trigger a job to refresh it.

refresh_timeout = 60

Timeout period during which no new tasks will be created for a single cache item. This time should cover the normal time required to refresh the cache.

task_options = None

Overrides options for refresh_cache.apply_async (e.g. queue).

There are also several methods intended to be overridden and customised:

class cacheback.base.Job

A cached read job.

This is the core class for the package which is intended to be subclassed to allow the caching behaviour to be customised.

empty()

Return the appropriate value for a cache MISS (and when we defer the repopulation of the cache)

expiry(*args, **kwargs)

Return the expiry timestamp for this item.

fetch(*args, **kwargs)

Return the data for this job - this is where the expensive work should be done.

key(*args, **kwargs)

Return the cache key to use.

If you’re passing anything but primitive types to the get method, it’s likely that you’ll need to override this method.

key(*args, **kwargs)

Return the cache key to use.

If you’re passing anything but primitive types to the get method, it’s likely that you’ll need to override this method.

process_result(result, call, cache_status, sync_fetch=None)

Transform the fetched data right before returning from .get(…)

Parameters
  • result – The result to be returned

  • call – A named tuple with properties ‘args’ and ‘kwargs that holds the call args and kwargs

  • cache_status – A status integrer, accessible as class constants self.MISS, self.HIT, self.STALE

  • sync_fetch – A boolean indicating whether a synchronous fetch was performed. A value of None indicates that no fetch was required (ie the result was a cache hit).

should_missing_item_be_fetched_synchronously(*args, **kwargs)

Return whether to refresh an item synchronously when it is missing from the cache

should_stale_item_be_fetched_synchronously(delta, *args, **kwargs)

Return whether to refresh an item synchronously when it is found in the cache but stale

timeout(*args, **kwargs)

Return the refresh timeout for this item

Queryset jobs

There are two classes for easy caching of ORM reads. These don’t need subclassing but rather take the model class as a __init__ parameter.

class cacheback.jobs.QuerySetFilterJob(model, lifetime=None, fetch_on_miss=None, cache_alias=None, task_options=None)

For ORM reads that use the filter method.

fetch(*args, **kwargs)

Return the data for this job - this is where the expensive work should be done.

class cacheback.jobs.QuerySetGetJob(model, lifetime=None, fetch_on_miss=None, cache_alias=None, task_options=None)

For ORM reads that use the get method.

fetch(*args, **kwargs)

Return the data for this job - this is where the expensive work should be done.

Example usage:

from django.contrib.auth import models
from django.shortcuts import render
from cacheback.jobs import QuerySetGetJob, QuerySetFilterJob

def user_detail(request, username):
    user = QuerySetGetJob(models.User).get(username=username)
    return render(request, 'user.html', {'user': user})

def staff(request):
    staff = QuerySetFilterJob(models.User).get(is_staff=True)
    return render(request, 'staff.html', {'users': staff})

These classes are helpful for simple ORM reads but won’t be suitable for more complicated queries where filter is chained together with exclude.