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
.