0
# Core Scheduler Management
1
2
Primary scheduler functionality that integrates APScheduler with Flask applications. Provides initialization, lifecycle management, configuration loading, and event handling capabilities.
3
4
## Capabilities
5
6
### APScheduler Class
7
8
Main scheduler class that wraps APScheduler functionality and provides Flask integration.
9
10
```python { .api }
11
class APScheduler:
12
"""
13
Provides a scheduler integrated to Flask.
14
15
Attributes:
16
allowed_hosts (list): List of hostnames allowed to start scheduler
17
auth (HTTPAuth): Authentication handler for API endpoints
18
api_enabled (bool): Whether REST API is enabled
19
api_prefix (str): URL prefix for API endpoints
20
endpoint_prefix (str): Prefix for Flask endpoint names
21
app (Flask): Flask application instance
22
"""
23
24
def __init__(self, scheduler=None, app=None):
25
"""
26
Initialize APScheduler.
27
28
Args:
29
scheduler: APScheduler instance (BackgroundScheduler if None)
30
app: Flask application instance
31
"""
32
```
33
34
### Initialization and Configuration
35
36
Setup and configuration methods for integrating with Flask applications.
37
38
```python { .api }
39
def init_app(self, app):
40
"""
41
Initialize the APScheduler with a Flask application instance.
42
43
Args:
44
app (Flask): Flask application instance
45
46
Note:
47
- Loads configuration from Flask config
48
- Loads job definitions from config
49
- Sets up REST API if enabled
50
- Sets app.apscheduler = self
51
"""
52
```
53
54
### Scheduler Properties
55
56
Read-only properties providing scheduler state and information.
57
58
```python { .api }
59
@property
60
def host_name(self) -> str:
61
"""Get the host name."""
62
63
@property
64
def running(self) -> bool:
65
"""Get true whether the scheduler is running."""
66
67
@property
68
def state(self) -> int:
69
"""Get the state of the scheduler (STATE_RUNNING, STATE_PAUSED, STATE_STOPPED)."""
70
71
@property
72
def scheduler(self):
73
"""Get the base APScheduler instance."""
74
75
@property
76
def task(self):
77
"""Get the scheduler decorator for job definitions."""
78
```
79
80
### Lifecycle Management
81
82
Methods for controlling scheduler execution state.
83
84
```python { .api }
85
def start(self, paused=False):
86
"""
87
Start the scheduler.
88
89
Args:
90
paused (bool): If True, don't start job processing until resume is called
91
92
Note:
93
- Prevents double-start in Flask debug mode
94
- Checks hostname against allowed_hosts
95
- Only starts if hostname is in allowed_hosts or "*" is allowed
96
"""
97
98
def shutdown(self, wait=True):
99
"""
100
Shut down the scheduler.
101
102
Args:
103
wait (bool): True to wait until all currently executing jobs have finished
104
105
Raises:
106
SchedulerNotRunningError: If scheduler has not been started yet
107
"""
108
109
def pause(self):
110
"""
111
Pause job processing in the scheduler.
112
113
Note:
114
Prevents scheduler from waking up for job processing until resume() is called.
115
Does not stop already running jobs.
116
"""
117
118
def resume(self):
119
"""Resume job processing in the scheduler."""
120
```
121
122
### Event Management
123
124
Methods for managing scheduler event listeners.
125
126
```python { .api }
127
def add_listener(self, callback, mask=EVENT_ALL):
128
"""
129
Add a listener for scheduler events.
130
131
Args:
132
callback: Callable that takes one argument (event object)
133
mask (int): Bitmask indicating which events to listen for
134
135
Note:
136
When a matching event occurs, callback is executed with the event object.
137
If mask is not provided, callback receives events of all types.
138
"""
139
140
def remove_listener(self, callback):
141
"""Remove a previously added event listener."""
142
```
143
144
### Authentication Decorator
145
146
Decorator for registering authentication functions.
147
148
```python { .api }
149
def authenticate(self, func):
150
"""
151
A decorator that is used to register a function to authenticate a user.
152
153
Args:
154
func: The callback function to authenticate users
155
156
Returns:
157
The decorated function
158
159
Example:
160
@scheduler.authenticate
161
def authenticate(auth):
162
return auth["username"] == "admin" and auth["password"] == "secret"
163
"""
164
```
165
166
## Usage Examples
167
168
### Basic Scheduler Setup
169
170
```python
171
from flask import Flask
172
from flask_apscheduler import APScheduler
173
174
app = Flask(__name__)
175
scheduler = APScheduler()
176
scheduler.init_app(app)
177
scheduler.start()
178
```
179
180
### Configuration-Based Setup
181
182
```python
183
from flask import Flask
184
from flask_apscheduler import APScheduler
185
186
class Config:
187
SCHEDULER_API_ENABLED = True
188
SCHEDULER_API_PREFIX = "/api/scheduler"
189
SCHEDULER_ALLOWED_HOSTS = ["localhost", "production.example.com"]
190
191
app = Flask(__name__)
192
app.config.from_object(Config())
193
194
scheduler = APScheduler()
195
scheduler.init_app(app)
196
scheduler.start()
197
```
198
199
### Event Listening
200
201
```python
202
from apscheduler.events import EVENT_JOB_EXECUTED, EVENT_JOB_ERROR
203
204
def job_executed(event):
205
print(f"Job {event.job_id} executed")
206
207
def job_failed(event):
208
print(f"Job {event.job_id} failed: {event.exception}")
209
210
scheduler.add_listener(job_executed, EVENT_JOB_EXECUTED)
211
scheduler.add_listener(job_failed, EVENT_JOB_ERROR)
212
```
213
214
### Hostname Restrictions
215
216
```python
217
# Allow scheduler to run only on specific hosts
218
app.config["SCHEDULER_ALLOWED_HOSTS"] = ["worker1.example.com", "worker2.example.com"]
219
220
# Allow on any host (default)
221
app.config["SCHEDULER_ALLOWED_HOSTS"] = ["*"]
222
```