API reference¶
The public surface, from the models most projects touch down to the drivers. architecture explains how the layers fit together.
Models¶
Unmanaged Django models whose records live in Redis. task_id and group_id
are the primary keys. Field names, verbose names, help texts and Meta options
match django-celery-results; see parity.
Models stored in Redis.
The models are unmanaged: Django never creates tables for them. Saving and
deleting go to the configured Redis store, and objects returns a
RedisQuerySet, so the admin, forms and signals work as with database models.
Managers¶
TaskResult.objects, GroupResult.objects and ChordCounter.objects. They
carry the methods the backend calls, plus delete_expired() for cleanup.
Model managers.
Bases: RedisManager
Generic manager for celery results.
Create or update one record and return the instance.
Saving an instance costs a read and a write. When nothing listens for the model's save signals, the record is written in a single round trip instead, which is the path Celery workers take for every state change.
Bases: ResultManager
Manager for :class:~.models.TaskResult models.
store_result(
content_type,
content_encoding,
task_id,
result,
status,
traceback=None,
meta=None,
periodic_task_name=None,
task_name=None,
task_args=None,
task_kwargs=None,
worker=None,
using=None,
**kwargs,
)
Store the result and status of a task.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
content_type
|
str
|
Mime-type of result and meta content. |
required |
content_encoding
|
str
|
Type of encoding (e.g. binary/utf-8). |
required |
task_id
|
str
|
Id of task. |
required |
periodic_task_name
|
str
|
Celery Periodic task name. |
None
|
task_name
|
str
|
Celery task name. |
None
|
task_args
|
str
|
Task arguments. |
None
|
task_kwargs
|
str
|
Task kwargs. |
None
|
result
|
str
|
The serialized return value of the task, or an exception instance raised by the task. |
required |
status
|
str
|
Task status. See :mod: |
required |
worker
|
str
|
Worker that executes the task. |
None
|
using
|
str
|
Accepted for compatibility; ignored. |
None
|
traceback
|
str
|
The traceback string taken at the point of exception (only passed if the task failed). |
None
|
meta
|
str
|
Serialized result meta data (this contains e.g. children). |
None
|
Other Parameters:
| Name | Type | Description |
|---|---|---|
date_started |
datetime
|
When the task started. |
exception_retry_count |
int
|
How many times to retry on Redis connection errors. The default is to retry twice. |
Bases: RedisManager
Manager for :class:~.models.ChordCounter models.
Atomically decrement the counter of group_id.
Returns None if there is no counter. Otherwise returns an unsaved
instance holding the remaining count; once the count reaches zero the
counter is deleted and the instance carries its sub_tasks.
Retry the decorated function on Redis connection errors.
Other Parameters:
| Name | Type | Description |
|---|---|---|
max_retries |
int
|
Maximum number of retries. Default one retry.
Callers can override it with |
Backend¶
The Celery result backend. Registered as django-redis-db in the
celery.result_backends entry point group, so
CELERY_RESULT_BACKEND = "django-redis-db" is enough.
Celery result backend storing results through the Redis models.
Bases: BaseDictBackend
Result backend using the Redis-stored models to keep task state.
Check if an exception is safe to retry.
Redis connection and timeout errors are retried when
result_backend_always_retry is enabled; the connection pool opens a
new connection on the next attempt.
Add a ChordCounter with the expected number of results.
Called on finishing each part of a Chord header.
Add the callback to the queue or mark the callback as failed.
Implementation borrowed from celery.app.builtins.unlock_chord
QuerySet¶
What the managers return. It subclasses django.db.models.QuerySet and
implements the parts that can be answered from Redis; everything else raises
NotSupportedError. See parity for the supported lookups.
A QuerySet whose rows live in Redis.
RedisQuerySet subclasses Django's QuerySet so that code checking
isinstance(obj, QuerySet) (the admin does) keeps working. Its query is a
RedisQuery holding a lookup tree instead of SQL. Methods that only use the
public query API (filter, exclude, order_by, get, slicing, ...)
are inherited; methods that would build SQL are overridden or raise
NotSupportedError.
Bases: QuerySet
The query state of a RedisQuerySet.
Exposes the attributes of django.db.models.sql.Query that Django's
QuerySet and admin read, with a lookup tree as where.
Bases: from_queryset(RedisQuerySet)
Stores¶
One store per model, built from the settings by
django_celery_results_redis.store.get_store(). Store is the base and the
raw driver; the other two add query pushdown. A dotted path to a Store
subclass is a valid value for the DRIVER setting, which is how a project can
add its own.
Redis clients and per-model stores built from the app settings.
Return the current master of a sentinel:// URL.
The URL lists the sentinels separated by ;, like Celery's sentinel
result backend, for example
sentinel://host-a:26379;sentinel://host-b:26379/0.
Claim the key prefix for this format version, or refuse to use it.
property
¶
Whether records carry index fields besides their own.
Index fields to write for values, including the primary key.
Index fields a rename has to rewrite for the new primary key.
Store values (None clears a field) for the record pk.
mode is "upsert", "insert" (fails if the record exists) or
"update" (does nothing if it does not). on_create values are
only written when the record is created. Returns (created, record),
or None when an update found no record.
Write (pk, values) pairs, one round trip per batch.
Values are stored as given: no automatic timestamps are applied, which is what importing existing results needs.
Decrement a chord counter.
Returns None if the counter does not exist, otherwise
(remaining, sub_tasks). sub_tasks is only returned, and the
counter deleted, once remaining reaches zero.
Bases: PushdownStore
Read the distinct values of a tag field from the value counters.
Search index¶
Optional. Built when SEARCH is set, used by every driver. See
drivers.
Optional RediSearch index for substring searches.
RediSearch matches whole tags and tokens, and its wildcard matching is capped
by MAXEXPANSIONS, so neither can answer icontains exactly. This index
instead stores the trigrams of each searchable field. A term matches only
records holding every trigram of that term, which is a superset of the real
matches: the store evaluates the lookup itself on the records the index
returns, so the result is exactly what the in-memory evaluator would give.
Values longer than SEARCH_MAX_TEXT are not tokenized; their field is
marked as overflowing instead, which keeps the record in every candidate set
for that field.
Trigram index over the searchable fields of one model.
Settings¶
app_settings reads DJANGO_CELERY_RESULTS_REDIS on every access, so
override_settings works in tests. settings documents each key.
Access to the DJANGO_CELERY_RESULTS_REDIS setting.
module-attribute
¶
DEFAULTS = {
"DRIVER": "indexed",
"URL": "redis://localhost:6379/0",
"CLIENT_KWARGS": {},
"CLIENT_FACTORY": None,
"KEY_PREFIX": "dcrr",
"ALLOW_EDITS": None,
"TASK_ID_MAX_LENGTH": None,
"SCAN_COUNT": 1000,
"BATCH_SIZE": 500,
"RESULT_TTL": None,
"ID_FIRST_URLS": False,
"SEARCH": None,
"SEARCH_MAX_TEXT": 4096,
"SEARCH_MAX_CANDIDATES": 50000,
"SENTINEL_MASTER_NAME": "mymaster",
"SENTINEL_KWARGS": {},
}
Read the setting on every access so override_settings is honoured.