0
# Job Management
1
2
Comprehensive job management capabilities for creating, modifying, and controlling scheduled jobs. Supports both programmatic job creation and decorator-based job definitions with multiple trigger types.
3
4
## Capabilities
5
6
### Job Creation and Removal
7
8
Methods for adding and removing jobs from the scheduler.
9
10
```python { .api }
11
def add_job(self, id, func, **kwargs):
12
"""
13
Add the given job to the job list and wake up the scheduler if it's already running.
14
15
Args:
16
id (str): Explicit identifier for the job (for modifying it later)
17
func: Callable (or textual reference to one) to run at the given time
18
**kwargs: Additional job configuration options including trigger parameters
19
20
Returns:
21
Job: The created job object
22
23
Trigger Options:
24
trigger (str): Type of trigger ("date", "interval", "cron")
25
26
Date trigger:
27
run_date: When to run the job
28
timezone: Timezone for the run_date
29
30
Interval trigger:
31
weeks, days, hours, minutes, seconds: Interval components
32
start_date: When to start the interval
33
end_date: When to stop the interval
34
timezone: Timezone for dates
35
36
Cron trigger:
37
year, month, day, week, day_of_week: Cron schedule fields
38
hour, minute, second: Time components
39
start_date, end_date: Date range bounds
40
timezone: Timezone for schedule
41
42
Job Options:
43
name: Human-readable name for the job
44
misfire_grace_time: Seconds after scheduled time job can still run
45
max_instances: Maximum number of concurrent job instances
46
coalesce: Whether to combine multiple pending executions
47
"""
48
49
def remove_job(self, id, jobstore=None):
50
"""
51
Remove a job, preventing it from being run any more.
52
53
Args:
54
id (str): The identifier of the job
55
jobstore (str): Alias of the job store that contains the job
56
"""
57
58
def remove_all_jobs(self, jobstore=None):
59
"""
60
Remove all jobs from the specified job store, or all job stores if none is given.
61
62
Args:
63
jobstore (str): Alias of the job store
64
"""
65
```
66
67
### Job Querying
68
69
Methods for retrieving job information.
70
71
```python { .api }
72
def get_job(self, id, jobstore=None):
73
"""
74
Return the Job that matches the given ID.
75
76
Args:
77
id (str): The identifier of the job
78
jobstore (str): Alias of the job store that most likely contains the job
79
80
Returns:
81
Job: The job by the given ID, or None if it wasn't found
82
"""
83
84
def get_jobs(self, jobstore=None):
85
"""
86
Return a list of pending jobs (if scheduler hasn't started) and scheduled jobs.
87
88
Args:
89
jobstore (str): Alias of the job store
90
91
Returns:
92
list[Job]: List of job objects
93
"""
94
```
95
96
### Job Modification
97
98
Methods for modifying existing job properties and scheduling.
99
100
```python { .api }
101
def modify_job(self, id, jobstore=None, **changes):
102
"""
103
Modify the properties of a single job.
104
105
Args:
106
id (str): The identifier of the job
107
jobstore (str): Alias of the job store that contains the job
108
**changes: Job properties to modify (same as add_job kwargs)
109
110
Returns:
111
Job: The modified job object
112
113
Note:
114
If "trigger" is in changes, the job will be rescheduled with new trigger.
115
All trigger parameters can be modified (run_date, interval components, cron fields).
116
"""
117
```
118
119
### Job State Control
120
121
Methods for controlling individual job execution state.
122
123
```python { .api }
124
def pause_job(self, id, jobstore=None):
125
"""
126
Pause the given job until it is explicitly resumed.
127
128
Args:
129
id (str): The identifier of the job
130
jobstore (str): Alias of the job store that contains the job
131
"""
132
133
def resume_job(self, id, jobstore=None):
134
"""
135
Resume the schedule of the given job, or remove job if its schedule is finished.
136
137
Args:
138
id (str): The identifier of the job
139
jobstore (str): Alias of the job store that contains the job
140
"""
141
142
def run_job(self, id, jobstore=None):
143
"""
144
Run the given job without scheduling it.
145
146
Args:
147
id (str): The identifier of the job
148
jobstore (str): Alias of the job store that contains the job
149
150
Raises:
151
JobLookupError: If the job is not found
152
"""
153
```
154
155
### Decorator-Based Job Definition
156
157
Task decorator for defining jobs using decorators.
158
159
```python { .api }
160
@scheduler.task(trigger, id=None, **trigger_args)
161
def job_function():
162
"""
163
Decorator for scheduling functions as jobs.
164
165
Args:
166
trigger (str): Trigger type ("interval", "cron", "date")
167
id (str): Job identifier (uses function name if None)
168
**trigger_args: Trigger-specific arguments
169
170
Returns:
171
The decorated function
172
"""
173
```
174
175
## Usage Examples
176
177
### Programmatic Job Creation
178
179
```python
180
# Interval job - runs every 30 seconds
181
scheduler.add_job(
182
id="heartbeat",
183
func=send_heartbeat,
184
trigger="interval",
185
seconds=30,
186
name="System Heartbeat"
187
)
188
189
# Cron job - runs daily at midnight
190
scheduler.add_job(
191
id="daily_cleanup",
192
func=cleanup_temp_files,
193
trigger="cron",
194
hour=0,
195
minute=0,
196
name="Daily Cleanup"
197
)
198
199
# Date job - runs once at specific time
200
from datetime import datetime, timedelta
201
run_time = datetime.now() + timedelta(hours=1)
202
scheduler.add_job(
203
id="delayed_task",
204
func=process_data,
205
trigger="date",
206
run_date=run_time,
207
args=[data_file],
208
kwargs={"format": "json"}
209
)
210
```
211
212
### Decorator-Based Job Definition
213
214
```python
215
# Interval job using decorator
216
@scheduler.task("interval", id="status_check", seconds=60)
217
def check_system_status():
218
print("Checking system status...")
219
220
# Cron job using decorator
221
@scheduler.task("cron", id="weekly_report", day_of_week="sun", hour=9)
222
def generate_weekly_report():
223
print("Generating weekly report...")
224
225
# Job with misfire grace time
226
@scheduler.task("interval", id="important_task", minutes=10, misfire_grace_time=300)
227
def important_periodic_task():
228
print("Running important task...")
229
```
230
231
### Job Modification
232
233
```python
234
# Modify job schedule
235
scheduler.modify_job("heartbeat", seconds=60) # Change from 30s to 60s
236
237
# Change cron job time
238
scheduler.modify_job("daily_cleanup", hour=2, minute=30) # Change to 2:30 AM
239
240
# Modify job function and arguments
241
scheduler.modify_job("data_processor", func=new_processor, args=[new_data])
242
```
243
244
### Job State Management
245
246
```python
247
# Pause and resume jobs
248
scheduler.pause_job("heartbeat")
249
scheduler.resume_job("heartbeat")
250
251
# Run job immediately (outside normal schedule)
252
scheduler.run_job("daily_cleanup")
253
254
# Remove jobs
255
scheduler.remove_job("old_task")
256
scheduler.remove_all_jobs() # Remove all jobs
257
```
258
259
### Configuration-Based Job Loading
260
261
```python
262
class Config:
263
JOBS = [
264
{
265
"id": "job1",
266
"func": "mymodule:my_function",
267
"args": (1, 2),
268
"trigger": "interval",
269
"seconds": 10
270
},
271
{
272
"id": "job2",
273
"func": "mymodule:another_function",
274
"trigger": "cron",
275
"day_of_week": "mon-fri",
276
"hour": 9,
277
"minute": 0
278
}
279
]
280
281
app.config.from_object(Config())
282
scheduler.init_app(app) # Jobs automatically loaded
283
```
284
285
### Advanced Job Options
286
287
```python
288
scheduler.add_job(
289
id="batch_processor",
290
func=process_batch,
291
trigger="interval",
292
minutes=5,
293
max_instances=3, # Allow up to 3 concurrent executions
294
coalesce=True, # Combine multiple pending executions
295
misfire_grace_time=60, # Allow 60 seconds past schedule time
296
replace_existing=True # Replace job if ID already exists
297
)
298
```