JobQueue: Simpler API for adding jobs

[jh0ker]

A version of #482 with less bullshit.

New API for adding jobs

Noam (and I) thought of a new, simpler API for the JobQueue to add new jobs, with the goal to replace the current paradigm of creating Job instances and using JobQueue.put to add them to the job queue. For now, there are three new methods in the JobQueue class:

• JobQueue.run_once(self, callback, when, context=None, name=None)
• JobQueue.run_repeating(self, callback, interval, first=None, context=None, name=None)
• JobQueue.run_daily(self, callback, time, days=Days.EVERY_DAY, context=None, name=None)

Each of them creates a Job instance and uses the JobQueue.put method internally, but they hide the unimportant things from the user. The new Job is also returned from the method.

>>> from datetime import datetime, time, timedelta
>>> job_queue.run_once(new_year_callback, datetime(2017, 1, 1))
<Job ...>
>>> job_queue.run_repeating(update_channel_callback, timedelta(minutes=10), first=datetime.now())
<Job ...>
>>> job_queue.run_daily(alarm_clock_callback, time(8, 30))
<Job ...>

The "old" way of using Job instances and JobQueue.put yourself still works and should be 100% backwards compatible.

JobQueue.put

The JobQueue.put method has been extended to accept absolute times as datetime.datetime and datetime.time.

>>> from datetime import datetime, time, timedelta
>>> job_queue.put(happy_new_year_job, next_t=datetime(2017, 1, 1))
>>> job_queue.put(alarm_clock_job, next_t=time(8, 30))
>>> midnight_job = Job(midnight_callback, timedelta(days=1))
>>> job_queue.put(midnight_job, next_t=time(0, 0))

If you pass a datetime.time object for next_t and it's already later than the specified time (eg it's 10:00 and next_t is time(8, 30)), the job will execute the next day.

I made the interval parameter for Job optional, so you can just leave it for non-repeating jobs (however, you must explicitly pass repeat=False)