0
# Django Celery Results
1

2
A Django extension providing database and cache backends for storing Celery task results. It enables developers to store and retrieve Celery task results using Django's ORM models and caching framework, allowing task results to be queried like any other Django model.
3

4
## Package Information
5

6
- **Package Name**: django-celery-results
7
- **Language**: Python
8
- **Installation**: `pip install django-celery-results`
9

10
## Core Imports
11

12
```python
13
import django_celery_results
14
```
15

16
Backend imports for configuration:
17

18
```python
19
from django_celery_results.backends import DatabaseBackend, CacheBackend
20
```
21

22
Model imports for querying results:
23

24
```python
25
from django_celery_results.models import TaskResult, GroupResult, ChordCounter
26
```
27

28
App configuration import:
29

30
```python
31
from django_celery_results.apps import CeleryResultConfig
32
```
33

34
Utility function imports:
35

36
```python
37
from django_celery_results.utils import now
38
```
39

40
## Basic Usage
41

42
### Installation and Configuration
43

44
```python
45
# settings.py
46
INSTALLED_APPS = [
47
    # ... other apps
48
    'django_celery_results',
49
]
50

51
# Configure Celery to use Django database backend
52
CELERY_RESULT_BACKEND = 'django-db'
53

54
# Or use Django cache backend
55
# CELERY_RESULT_BACKEND = 'django-cache'
56

57
# Optional: Configure task ID max length (useful for MySQL)
58
DJANGO_CELERY_RESULTS_TASK_ID_MAX_LENGTH = 191
59
```
60

61
### Querying Task Results
62

63
```python
64
from django_celery_results.models import TaskResult
65
from celery.result import AsyncResult
66

67
# Query task results using Django ORM
68
recent_tasks = TaskResult.objects.filter(
69
    status='SUCCESS',
70
    date_done__gte=timezone.now() - timedelta(hours=1)
71
)
72

73
for task in recent_tasks:
74
    print(f"Task {task.task_id}: {task.status}")
75
    print(f"Result: {task.result}")
76

77
# Use Celery's AsyncResult with the backend
78
result = AsyncResult('task-id-here')
79
print(f"Task state: {result.state}")
80
print(f"Task result: {result.result}")
81
```
82

83
## Architecture
84

85
Django Celery Results provides two main backend implementations:
86

87
- **DatabaseBackend**: Stores task results in Django database tables using the ORM
88
- **CacheBackend**: Stores task results in Django's cache framework
89
- **Models**: Django models (TaskResult, GroupResult, ChordCounter) for database storage
90
- **Managers**: Custom managers providing database operations with transaction retry logic
91
- **Admin Integration**: Django admin interfaces for browsing and managing task results
92
- **REST Views**: HTTP endpoints for checking task and group status via JSON APIs
93

94
The package integrates seamlessly with Celery's result backend system while providing the full power of Django's ORM for querying and managing task results.
95

96
## Capabilities
97

98
### Result Backend Configuration
99

100
Configuration of Celery result backends using Django's database or cache frameworks. Provides both database-based and cache-based storage with automatic encoding/decoding of task results.
101

102
```python { .api }
103
class DatabaseBackend(BaseDictBackend):
104
    def __init__(self, *args, **kwargs): ...
105
    def exception_safe_to_retry(self, exc): ...
106
    def encode_content(self, data): ...
107
    def decode_content(self, obj, content): ...
108
    def cleanup(self): ...
109

110
class CacheBackend(KeyValueStoreBackend):
111
    def __init__(self, *args, **kwargs): ...
112
    def get(self, key): ...
113
    def set(self, key, value): ...
114
    def delete(self, key): ...
115
```
116

117
[Backend Configuration](./backends.md)
118

119
### Task Result Models
120

121
Django models for storing and querying Celery task results, group results, and chord coordination data. Provides full ORM capabilities for result management and includes custom managers with retry logic.
122

123
```python { .api }
124
class TaskResult(models.Model):
125
    task_id: models.CharField
126
    task_name: models.CharField
127
    status: models.CharField
128
    result: models.TextField
129
    date_created: models.DateTimeField
130
    date_done: models.DateTimeField
131
    
132
    def as_dict(self): ...
133

134
class GroupResult(models.Model):
135
    group_id: models.CharField
136
    result: models.TextField
137
    date_created: models.DateTimeField
138
    date_done: models.DateTimeField
139
    
140
    def as_dict(self): ...
141

142
class ChordCounter(models.Model):
143
    group_id: models.CharField
144
    sub_tasks: models.TextField
145
    count: models.PositiveIntegerField
146
    
147
    def group_result(self, app=None): ...
148
```
149

150
[Task Result Models](./models.md)
151

152
### Admin Interface
153

154
Django admin integration for browsing, searching, and managing task results through the web interface. Provides read-only or editable views based on configuration.
155

156
```python { .api }
157
class TaskResultAdmin(admin.ModelAdmin):
158
    model: TaskResult
159
    list_display: tuple
160
    list_filter: tuple
161
    search_fields: tuple
162
    
163
    def get_readonly_fields(self, request, obj=None): ...
164

165
class GroupResultAdmin(admin.ModelAdmin):
166
    model: GroupResult
167
    list_display: tuple
168
    search_fields: tuple
169
```
170

171
[Admin Interface](./admin.md)
172

173
### REST API Views
174

175
HTTP endpoints for checking task and group execution status, returning JSON responses suitable for web applications and AJAX requests.
176

177
```python { .api }
178
def task_status(request, task_id):
179
    """Get detailed task status and result in JSON format."""
180
    
181
def is_task_successful(request, task_id):
182
    """Check if a task completed successfully."""
183
    
184
def group_status(request, group_id):
185
    """Get detailed status for all tasks in a group."""
186
    
187
def is_group_successful(request, group_id):
188
    """Check if all tasks in a group completed successfully."""
189
```
190

191
[REST API Views](./views.md)
192

193
### Django App Configuration
194

195
Django application configuration class providing package metadata and settings for the django-celery-results app.
196

197
```python { .api }
198
class CeleryResultConfig(AppConfig):
199
    """Default configuration for the django_celery_results app."""
200

201
    name: str  # 'django_celery_results'
202
    label: str  # 'django_celery_results'  
203
    verbose_name: str  # 'Celery Results'
204
    default_auto_field: str  # 'django.db.models.AutoField'
205
```
206

207
### Utility Functions
208

209
Helper functions for time handling that work correctly with Django timezone settings.
210

211
```python { .api }
212
def now():
213
    """
214
    Return the current date and time with proper timezone handling.
215
    
216
    Returns:
217
        datetime: Current timestamp respecting Django USE_TZ setting
218
    """
219
```