Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

JobQueue: Simpler API for adding jobs #484

merged 9 commits into from Dec 20, 2016


None yet
2 participants
Copy link

jh0ker commented Dec 14, 2016

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),
<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.


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)

jh0ker and others added some commits Dec 13, 2016 stability improvments
 - Job.job_queue is now weakref.proxy reducing the risk of cyclic
   pointers preventing Job object from being deleted.
 - JobQueue._put(): raise if both next_t and job.interval are None
 - Don't put repeating job back to queue if user had disabled it was
   disabled during the time of execution.
 - New method: Job.is_removed() - promising a consistent API (instead of
   access to private member Job._remove)
 - Documentation fixes.

@tsnoam tsnoam merged commit 7f6b017 into master Dec 20, 2016

2 checks passed

continuous-integration/travis-ci/pr The Travis CI build passed
coverage/coveralls First build on master at 92.454%

@rahiel rahiel deleted the jobqueue-absolute-simple branch Feb 5, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.