0
# Validation and Utilities
1
2
Validation functions for cron expressions and utility functions for working with timezone-aware datetime objects and database-backed scheduling operations.
3
4
## Capabilities
5
6
### Cron Expression Validation
7
8
Comprehensive validation functions for cron expression fields, ensuring proper format and value ranges for minute, hour, day, month, and day-of-week fields.
9
10
```python { .api }
11
def crontab_validator(value: str):
12
"""
13
Validate a complete cron expression string.
14
15
Parameters:
16
- value (str): Complete cron expression to validate
17
18
Raises:
19
- ValidationError: If cron expression format is invalid
20
"""
21
22
def minute_validator(value: str):
23
"""
24
Validate cron minute field (0-59).
25
26
Parameters:
27
- value (str): Minute field value to validate
28
29
Raises:
30
- ValidationError: If minute value is invalid
31
"""
32
33
def hour_validator(value: str):
34
"""
35
Validate cron hour field (0-23).
36
37
Parameters:
38
- value (str): Hour field value to validate
39
40
Raises:
41
- ValidationError: If hour value is invalid
42
"""
43
44
def day_of_month_validator(value: str):
45
"""
46
Validate cron day of month field (1-31).
47
48
Parameters:
49
- value (str): Day of month field value to validate
50
51
Raises:
52
- ValidationError: If day of month value is invalid
53
"""
54
55
def month_of_year_validator(value: str):
56
"""
57
Validate cron month field (1-12).
58
59
Parameters:
60
- value (str): Month field value to validate
61
62
Raises:
63
- ValidationError: If month value is invalid
64
"""
65
66
def day_of_week_validator(value: str):
67
"""
68
Validate cron day of week field (0-6).
69
70
Parameters:
71
- value (str): Day of week field value to validate
72
73
Raises:
74
- ValidationError: If day of week value is invalid
75
"""
76
```
77
78
### Timezone Utilities
79
80
Utility functions for handling timezone-aware datetime objects in Django environments, ensuring proper timezone conversion and current time retrieval.
81
82
```python { .api }
83
def make_aware(value: datetime.datetime) -> datetime.datetime:
84
"""
85
Force datetime to have timezone information.
86
87
Parameters:
88
- value (datetime): Datetime object to make timezone-aware
89
90
Returns:
91
- datetime: Timezone-aware datetime object
92
"""
93
94
def now() -> datetime.datetime:
95
"""
96
Return current date/time respecting Django timezone settings.
97
98
Returns:
99
- datetime: Current datetime with appropriate timezone
100
"""
101
102
def aware_now() -> datetime.datetime:
103
"""
104
Return timezone-aware current datetime.
105
106
Returns:
107
- datetime: Current timezone-aware datetime
108
"""
109
```
110
111
### Scheduler Utilities
112
113
Helper functions for working with database schedulers and checking scheduler configurations.
114
115
```python { .api }
116
def is_database_scheduler(scheduler) -> bool:
117
"""
118
Check if the provided scheduler is a database scheduler instance.
119
120
Parameters:
121
- scheduler: Scheduler instance to check
122
123
Returns:
124
- bool: True if scheduler is DatabaseScheduler instance
125
"""
126
```
127
128
### Model Helper Functions
129
130
Utility functions used internally by the schedule models for cron expression formatting and timezone handling.
131
132
```python { .api }
133
def cronexp(field) -> str:
134
"""
135
Convert cron field to string representation.
136
137
Parameters:
138
- field: Cron field value to convert
139
140
Returns:
141
- str: String representation of cron field
142
"""
143
144
def crontab_schedule_celery_timezone() -> str:
145
"""
146
Get timezone string from CELERY_TIMEZONE setting.
147
148
Returns:
149
- str: Timezone string (defaults to 'UTC')
150
"""
151
```
152
153
## Constants
154
155
### Timeout Constants
156
157
```python { .api }
158
NEVER_CHECK_TIMEOUT = 100000000 # Large timeout value for disabled tasks
159
```
160
161
### Period Constants
162
163
```python { .api }
164
DAYS = 'days'
165
HOURS = 'hours'
166
MINUTES = 'minutes'
167
SECONDS = 'seconds'
168
MICROSECONDS = 'microseconds'
169
170
PERIOD_CHOICES = [
171
(DAYS, 'Days'),
172
(HOURS, 'Hours'),
173
(MINUTES, 'Minutes'),
174
(SECONDS, 'Seconds'),
175
(MICROSECONDS, 'Microseconds'),
176
]
177
178
SINGULAR_PERIODS = [
179
(DAYS, 'Day'),
180
(HOURS, 'Hour'),
181
(MINUTES, 'Minute'),
182
(SECONDS, 'Second'),
183
(MICROSECONDS, 'Microsecond'),
184
]
185
```
186
187
### Solar Event Constants
188
189
```python { .api }
190
SOLAR_SCHEDULES = [
191
("dawn_astronomical", "Astronomical dawn"),
192
("dawn_civil", "Civil dawn"),
193
("dawn_nautical", "Nautical dawn"),
194
("dusk_astronomical", "Astronomical dusk"),
195
("dusk_civil", "Civil dusk"),
196
("dusk_nautical", "Nautical dusk"),
197
("solar_noon", "Solar noon"),
198
("sunrise", "Sunrise"),
199
("sunset", "Sunset"),
200
]
201
```
202
203
## Usage Examples
204
205
### Creating Validated Schedules
206
207
```python
208
from django_celery_beat.models import CrontabSchedule
209
from django_celery_beat.validators import crontab_validator
210
from django.core.exceptions import ValidationError
211
212
# Validate before creating cron schedule
213
try:
214
crontab_validator("0 2 * * 1") # Every Monday at 2 AM
215
schedule = CrontabSchedule.objects.create(
216
minute='0',
217
hour='2',
218
day_of_week='1',
219
day_of_month='*',
220
month_of_year='*'
221
)
222
except ValidationError as e:
223
print(f"Invalid cron expression: {e}")
224
```
225
226
### Working with Timezone-aware Datetimes
227
228
```python
229
from django_celery_beat.utils import make_aware, now, aware_now
230
from datetime import datetime
231
232
# Get current time with proper timezone
233
current_time = now()
234
aware_time = aware_now()
235
236
# Make a naive datetime timezone-aware
237
naive_dt = datetime(2023, 12, 25, 15, 30)
238
aware_dt = make_aware(naive_dt)
239
```
240
241
### Scheduler Detection
242
243
```python
244
from django_celery_beat.utils import is_database_scheduler
245
from django_celery_beat.schedulers import DatabaseScheduler
246
247
scheduler = DatabaseScheduler()
248
if is_database_scheduler(scheduler):
249
print("Using database scheduler")
250
```