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
```