0
# Django Celery Beat
1

2
Django Celery Beat provides database-backed periodic task scheduling for Django applications using Celery. It enables storing and managing periodic tasks in a Django database, allowing dynamic task scheduling through the Django Admin interface without requiring server restarts or configuration file changes.
3

4
## Package Information
5

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

10
## Core Imports
11

12
```python
13
from django_celery_beat.models import PeriodicTask, IntervalSchedule, CrontabSchedule
14
from django_celery_beat.schedulers import DatabaseScheduler
15
```
16

17
## Basic Usage
18

19
```python
20
from django_celery_beat.models import PeriodicTask, IntervalSchedule
21
import json
22

23
# Create an interval schedule (every 10 seconds)
24
schedule, created = IntervalSchedule.objects.get_or_create(
25
    every=10,
26
    period=IntervalSchedule.SECONDS,
27
)
28

29
# Create a periodic task
30
PeriodicTask.objects.create(
31
    interval=schedule,
32
    name='Import contacts every 10 seconds',
33
    task='myapp.tasks.import_contacts',
34
    args=json.dumps(['arg1', 'arg2']),
35
    kwargs=json.dumps({'be_careful': True}),
36
)
37
```
38

39
## Architecture
40

41
Django Celery Beat integrates with Django's ORM and Celery's beat scheduler:
42

43
- **Django Models**: Store schedule definitions and task configurations in database tables
44
- **Database Scheduler**: Replaces Celery's default file-based scheduler with database queries
45
- **Admin Integration**: Provides Django Admin interface for managing tasks
46
- **Signal System**: Automatically tracks changes to notify the beat service of schedule updates
47

48
## Capabilities
49

50
### Schedule Models
51

52
Database models for defining when periodic tasks should run, including interval-based, cron-like, solar event-based, and one-time scheduling patterns.
53

54
```python { .api }
55
class IntervalSchedule(models.Model):
56
    every: int
57
    period: str  # DAYS, HOURS, MINUTES, SECONDS, MICROSECONDS
58
    
59
class CrontabSchedule(models.Model):
60
    minute: str
61
    hour: str
62
    day_of_week: str
63
    day_of_month: str
64
    month_of_year: str
65
    timezone: timezone_field.TimeZoneField
66

67
class SolarSchedule(models.Model):
68
    event: str  # sunrise, sunset, solar_noon, etc.
69
    latitude: decimal.Decimal
70
    longitude: decimal.Decimal
71

72
class ClockedSchedule(models.Model):
73
    clocked_time: datetime.datetime
74
```
75

76
[Schedule Models](./schedule-models.md)
77

78
### Task Management
79

80
Core model and utilities for defining and managing periodic tasks, including task configuration, arguments, routing, and execution tracking.
81

82
```python { .api }
83
class PeriodicTask(models.Model):
84
    name: str
85
    task: str
86
    interval: ForeignKey[IntervalSchedule]
87
    crontab: ForeignKey[CrontabSchedule]
88
    solar: ForeignKey[SolarSchedule]
89
    clocked: ForeignKey[ClockedSchedule]
90
    args: str  # JSON encoded list
91
    kwargs: str  # JSON encoded dict
92
    enabled: bool
93
    one_off: bool
94

95
class PeriodicTasks(models.Model):
96
    @classmethod
97
    def changed(cls): ...
98
    @classmethod
99
    def update_changed(cls): ...
100
```
101

102
[Task Management](./task-management.md)
103

104
### Database Scheduler
105

106
Celery beat scheduler implementation that reads periodic tasks from the database instead of configuration files, enabling dynamic task management.
107

108
```python { .api }
109
class DatabaseScheduler(Scheduler):
110
    def setup_schedule(self): ...
111
    def all_as_schedule(self) -> dict: ...
112
    def schedule_changed(self) -> bool: ...
113
    def sync(self): ...
114

115
class ModelEntry(ScheduleEntry):
116
    def is_due(self) -> tuple[bool, float]: ...
117
    def save(self): ...
118
```
119

120
[Database Scheduler](./database-scheduler.md)
121

122
### Admin Interface
123

124
Django Admin integration providing web-based management interface for periodic tasks and schedules with custom forms, actions, and validation.
125

126
```python { .api }
127
class PeriodicTaskAdmin(ModelAdmin):
128
    def enable_tasks(self, request, queryset): ...
129
    def disable_tasks(self, request, queryset): ...
130
    def toggle_tasks(self, request, queryset): ...
131
    def run_tasks(self, request, queryset): ...
132

133
class TaskSelectWidget(Select):
134
    def tasks_as_choices(self) -> list[tuple[str, str]]: ...
135
```
136

137
[Admin Interface](./admin-interface.md)
138

139
### Validation and Utilities
140

141
Validation functions for cron expressions, timezone utilities, and helper functions for working with database-backed scheduling.
142

143
```python { .api }
144
def crontab_validator(value: str): ...
145
def minute_validator(value: str): ...
146
def hour_validator(value: str): ...
147
def day_of_month_validator(value: str): ...
148
def month_of_year_validator(value: str): ...
149
def day_of_week_validator(value: str): ...
150

151
def make_aware(value: datetime.datetime) -> datetime.datetime: ...
152
def now() -> datetime.datetime: ...
153
def aware_now() -> datetime.datetime: ...
154
def is_database_scheduler(scheduler) -> bool: ...
155
```
156

157
[Validation and Utilities](./validation-utilities.md)
158

159
### Django App Configuration
160

161
Django application configuration for integrating django-celery-beat with Django projects.
162

163
```python { .api }
164
class BeatConfig(AppConfig):
165
    name: str
166
    label: str  
167
    verbose_name: str
168
    default_auto_field: str
169
    
170
    def ready(self): ...
171
```
172

173
### Custom QuerySet
174

175
Enhanced QuerySet for PeriodicTask with optimization methods.
176

177
```python { .api }
178
class PeriodicTaskQuerySet(QuerySet):
179
    def enabled(self) -> 'PeriodicTaskQuerySet': ...
180
```
181

182
### Signal Management
183

184
Signal handling for automatic change tracking when tasks are modified.
185

186
```python { .api }
187
def signals_connect(): ...
188
```