1:mod:`sched` --- Event scheduler
2================================
3
4.. module:: sched
5   :synopsis: General purpose event scheduler.
6
7.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
8
9**Source code:** :source:`Lib/sched.py`
10
11.. index:: single: event scheduling
12
13--------------
14
15The :mod:`sched` module defines a class which implements a general purpose event
16scheduler:
17
18.. class:: scheduler(timefunc=time.monotonic, delayfunc=time.sleep)
19
20   The :class:`scheduler` class defines a generic interface to scheduling events.
21   It needs two functions to actually deal with the "outside world" --- *timefunc*
22   should be callable without arguments, and return  a number (the "time", in any
23   units whatsoever).  The *delayfunc* function should be callable with one
24   argument, compatible with the output of *timefunc*, and should delay that many
25   time units. *delayfunc* will also be called with the argument ``0`` after each
26   event is run to allow other threads an opportunity to run in multi-threaded
27   applications.
28
29   .. versionchanged:: 3.3
30      *timefunc* and *delayfunc* parameters are optional.
31
32   .. versionchanged:: 3.3
33      :class:`scheduler` class can be safely used in multi-threaded
34      environments.
35
36Example::
37
38   >>> import sched, time
39   >>> s = sched.scheduler(time.time, time.sleep)
40   >>> def print_time(a='default'):
41   ...     print("From print_time", time.time(), a)
42   ...
43   >>> def print_some_times():
44   ...     print(time.time())
45   ...     s.enter(10, 1, print_time)
46   ...     s.enter(5, 2, print_time, argument=('positional',))
47   ...     s.enter(5, 1, print_time, kwargs={'a': 'keyword'})
48   ...     s.run()
49   ...     print(time.time())
50   ...
51   >>> print_some_times()
52   930343690.257
53   From print_time 930343695.274 positional
54   From print_time 930343695.275 keyword
55   From print_time 930343700.273 default
56   930343700.276
57
58.. _scheduler-objects:
59
60Scheduler Objects
61-----------------
62
63:class:`scheduler` instances have the following methods and attributes:
64
65
66.. method:: scheduler.enterabs(time, priority, action, argument=(), kwargs={})
67
68   Schedule a new event. The *time* argument should be a numeric type compatible
69   with the return value of the *timefunc* function passed  to the constructor.
70   Events scheduled for the same *time* will be executed in the order of their
71   *priority*. A lower number represents a higher priority.
72
73   Executing the event means executing ``action(*argument, **kwargs)``.
74   *argument* is a sequence holding the positional arguments for *action*.
75   *kwargs* is a dictionary holding the keyword arguments for *action*.
76
77   Return value is an event which may be used for later cancellation of the event
78   (see :meth:`cancel`).
79
80   .. versionchanged:: 3.3
81      *argument* parameter is optional.
82
83   .. versionchanged:: 3.3
84      *kwargs* parameter was added.
85
86
87.. method:: scheduler.enter(delay, priority, action, argument=(), kwargs={})
88
89   Schedule an event for *delay* more time units. Other than the relative time, the
90   other arguments, the effect and the return value are the same as those for
91   :meth:`enterabs`.
92
93   .. versionchanged:: 3.3
94      *argument* parameter is optional.
95
96   .. versionchanged:: 3.3
97      *kwargs* parameter was added.
98
99.. method:: scheduler.cancel(event)
100
101   Remove the event from the queue. If *event* is not an event currently in the
102   queue, this method will raise a :exc:`ValueError`.
103
104
105.. method:: scheduler.empty()
106
107   Return ``True`` if the event queue is empty.
108
109
110.. method:: scheduler.run(blocking=True)
111
112   Run all scheduled events. This method will wait  (using the :func:`delayfunc`
113   function passed to the constructor) for the next event, then execute it and so
114   on until there are no more scheduled events.
115
116   If *blocking* is false executes the scheduled events due to expire soonest
117   (if any) and then return the deadline of the next scheduled call in the
118   scheduler (if any).
119
120   Either *action* or *delayfunc* can raise an exception.  In either case, the
121   scheduler will maintain a consistent state and propagate the exception.  If an
122   exception is raised by *action*, the event will not be attempted in future calls
123   to :meth:`run`.
124
125   If a sequence of events takes longer to run than the time available before the
126   next event, the scheduler will simply fall behind.  No events will be dropped;
127   the calling code is responsible for canceling  events which are no longer
128   pertinent.
129
130   .. versionchanged:: 3.3
131      *blocking* parameter was added.
132
133.. attribute:: scheduler.queue
134
135   Read-only attribute returning a list of upcoming events in the order they
136   will be run.  Each event is shown as a :term:`named tuple` with the
137   following fields:  time, priority, action, argument, kwargs.
138