Developer Interface

This part of the documentation covers all the interfaces of schedule. For parts where schedule depends on external libraries, we document the most important right here and provide links to the canonical documentation.

Main Interface

schedule.default_scheduler = <schedule.Scheduler object>

Default Scheduler object

schedule.jobs = []

Default Jobs list

schedule.every(interval=1)[source]

Calls every on the default scheduler instance.

schedule.run_pending()[source]

Calls run_pending on the default scheduler instance.

schedule.run_all(delay_seconds=0)[source]

Calls run_all on the default scheduler instance.

schedule.clear(tag=None)[source]

Calls clear on the default scheduler instance.

schedule.cancel_job(job)[source]

Calls cancel_job on the default scheduler instance.

schedule.next_run()[source]

Calls next_run on the default scheduler instance.

schedule.idle_seconds()[source]

Calls idle_seconds on the default scheduler instance.

Exceptions

exception schedule.CancelJob[source]

Can be returned from a job to unschedule itself.

Classes

class schedule.Scheduler[source]

Objects instantiated by the Scheduler are factories to create jobs, keep record of scheduled jobs and handle their execution.

run_pending()[source]

Run all jobs that are scheduled to run.

Please note that it is intended behavior that run_pending() does not run missed jobs. For example, if you’ve registered a job that should run every minute and you only call run_pending() in one hour increments then your job won’t be run 60 times in between but only once.

run_all(delay_seconds=0)[source]

Run all jobs regardless if they are scheduled to run or not.

A delay of delay seconds is added between each job. This helps distribute system load generated by the jobs more evenly over time.

Parameters:delay_seconds – A delay added between every executed job
clear(tag=None)[source]

Deletes scheduled jobs marked with the given tag, or all jobs if tag is omitted.

Parameters:tag – An identifier used to identify a subset of jobs to delete
cancel_job(job)[source]

Delete a scheduled job.

Parameters:job – The job to be unscheduled
every(interval=1)[source]

Schedule a new periodic job.

Parameters:interval – A quantity of a certain time unit
Returns:An unconfigured Job
next_run

Datetime when the next job should run.

Returns:A datetime object
idle_seconds
Returns:Number of seconds until next_run.
class schedule.Job(interval, scheduler=None)[source]

A periodic job as used by Scheduler.

Parameters:
  • interval – A quantity of a certain time unit
  • scheduler – The Scheduler instance that this job will register itself with once it has been fully configured in Job.do().

Every job runs at a given fixed time interval that is defined by:

  • a time unit
  • a quantity of time units defined by interval

A job is usually created and returned by Scheduler.every() method, which also defines its interval.

second
seconds
minute
minutes
hour
hours
day
days
week
weeks
monday
tuesday
wednesday
thursday
friday
saturday
sunday
tag(*tags)[source]

Tags the job with one or more unique indentifiers.

Tags must be hashable. Duplicate tags are discarded.

Parameters:tags – A unique list of Hashable tags.
Returns:The invoked job instance
at(time_str)[source]

Schedule the job every day at a specific time.

Calling this is only valid for jobs scheduled to run every N day(s).

Parameters:time_str – A string in XX:YY format.
Returns:The invoked job instance
to(latest)[source]

Schedule the job to run at an irregular (randomized) interval.

The job’s interval will randomly vary from the value given to every to latest. The range defined is inclusive on both ends. For example, every(A).to(B).seconds executes the job function every N seconds such that A <= N <= B.

Parameters:latest – Maximum interval between randomized job runs
Returns:The invoked job instance
do(job_func, *args, **kwargs)[source]

Specifies the job_func that should be called every time the job runs.

Any additional arguments are passed on to job_func when the job runs.

Parameters:job_func – The function to be scheduled
Returns:The invoked job instance
should_run
Returns:True if the job should be run now.
run()[source]

Run the job and immediately reschedule it.

Returns:The return value returned by the job_func