1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
|
#####################
Extending APScheduler
#####################
This document is meant to explain how to develop your custom triggers, job stores, executors and
schedulers.
Custom triggers
---------------
The built-in triggers cover the needs of the majority of all users.
However, some users may need specialized scheduling logic. To that end, the trigger system was made
pluggable.
To implement your scheduling logic, subclass :class:`~apscheduler.triggers.base.BaseTrigger`.
Look at the interface documentation in that class. Then look at the existing trigger
implementations. That should give you a good idea what is expected of a trigger implementation.
To use your trigger, you can use :meth:`~apscheduler.schedulers.base.BaseScheduler.add_job` like
this::
trigger = MyTrigger(arg1='foo')
scheduler.add_job(target, trigger)
You can also register it as a plugin so you can use the alternate form of
``add_job``::
scheduler.add_job(target, 'my_trigger', arg1='foo')
This is done by adding an entry point in your project's :file:`setup.py`::
...
entry_points={
'apscheduler.triggers': ['my_trigger = mytoppackage.subpackage:MyTrigger']
}
Custom job stores
-----------------
If you want to store your jobs in a fancy new NoSQL database, or a totally custom datastore, you
can implement your own job store by subclassing :class:`~apscheduler.jobstores.base.BaseJobStore`.
A job store typically serializes the :class:`~apscheduler.job.Job` objects given to it, and
constructs new Job objects from binary data when they are loaded from the backing store. It is
important that the job store restores the ``_scheduler`` and ``_jobstore_alias`` attribute of any
Job that it creates. Refer to existing implementations for examples.
It should be noted that :class:`~apscheduler.jobstores.memory.MemoryJobStore` is special in that it
does not deserialize the jobs. This comes with its own problems, which it handles in its own way.
If your job store does serialize jobs, you can of course use a serializer other than pickle.
You should, however, use the ``__getstate__`` and ``__setstate__`` special methods to respectively
get and set the Job state. Pickle uses them implicitly.
To use your job store, you can add it to the scheduler like this::
jobstore = MyJobStore()
scheduler.add_jobstore(jobstore, 'mystore')
You can also register it as a plugin so you can use can use the alternate form of
``add_jobstore``::
scheduler.add_jobstore('my_jobstore', 'mystore')
This is done by adding an entry point in your project's :file:`setup.py`::
...
entry_points={
'apscheduler.jobstores': ['my_jobstore = mytoppackage.subpackage:MyJobStore']
}
Custom executors
----------------
If you need custom logic for executing your jobs, you can create your own executor classes.
One scenario for this would be if you want to use distributed computing to run your jobs on other
nodes.
Start by subclassing :class:`~apscheduler.executors.base.BaseExecutor`.
The responsibilities of an executor are as follows:
* Performing any initialization when ``start()`` is called
* Releasing any resources when ``shutdown()`` is called
* Keeping track of the number of instances of each job running on it, and refusing to run more
than the maximum
* Notifying the scheduler of the results of the job
If your executor needs to serialize the jobs, make sure you either use pickle for it, or invoke the
``__getstate__`` and ``__setstate__`` special methods to respectively get and set the Job state.
Pickle uses them implicitly.
To use your executor, you can add it to the scheduler like this::
executor = MyExecutor()
scheduler.add_executor(executor, 'myexecutor')
You can also register it as a plugin so you can use can use the alternate form of
``add_executor``::
scheduler.add_executor('my_executor', 'myexecutor')
This is done by adding an entry point in your project's :file:`setup.py`::
...
entry_points={
'apscheduler.executors': ['my_executor = mytoppackage.subpackage:MyExecutor']
}
Custom schedulers
-----------------
A typical situation where you would want to make your own scheduler subclass is when you want to
integrate it with your
application framework of choice.
Your custom scheduler should always be a subclass of
:class:`~apscheduler.schedulers.base.BaseScheduler`. But if you're not adapting to a framework that
relies on callbacks, consider subclassing
:class:`~apscheduler.schedulers.blocking.BlockingScheduler` instead.
The most typical extension points for scheduler subclasses are:
* :meth:`~apscheduler.schedulers.base.BaseScheduler.start`
must be overridden to wake up the scheduler for the first time
* :meth:`~apscheduler.schedulers.base.BaseScheduler.shutdown`
must be overridden to release resources allocated during ``start()``
* :meth:`~apscheduler.schedulers.base.BaseScheduler.wakeup`
must be overridden to manage the timernotify the scheduler of changes in the job store
* :meth:`~apscheduler.schedulers.base.BaseScheduler._create_lock`
override if your framework uses some alternate locking implementation (like gevent)
* :meth:`~apscheduler.schedulers.base.BaseScheduler._create_default_executor`
override if you need to use an alternative default executor
.. important:: Remember to call the superclass implementations of overridden methods, even abstract
ones (unless they're empty).
The most important responsibility of the scheduler subclass is to manage the scheduler's sleeping
based on the return values of ``_process_jobs()``. This can be done in various ways, including
setting timeouts in ``wakeup()`` or running a blocking loop in ``start()``. Again, see the existing
scheduler classes for examples.
|
