Reference

This part of the documentation covers all the interfaces of schedule.

Main Interface

schedule.default_scheduler = <schedule.Scheduler object>

Default Scheduler object

schedule.jobs = []

Default Jobs list

schedule.every(interval: int = 1) → schedule.Job[source]

Calls every on the default scheduler instance.

schedule.run_pending() → None[source]

Calls run_pending on the default scheduler instance.

schedule.run_all(delay_seconds: int = 0) → None[source]

Calls run_all on the default scheduler instance.

schedule.get_jobs(tag: Optional[collections.abc.Hashable] = None) → List[schedule.Job][source]

Calls get_jobs on the default scheduler instance.

schedule.clear(tag: Optional[collections.abc.Hashable] = None) → None[source]

Calls clear on the default scheduler instance.

schedule.cancel_job(job: schedule.Job) → None[source]

Calls cancel_job on the default scheduler instance.

schedule.next_run(tag: Optional[collections.abc.Hashable] = None) → Optional[datetime.datetime][source]

Calls next_run on the default scheduler instance.

schedule.idle_seconds() → Optional[float][source]

Calls idle_seconds on the default scheduler instance.

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() → None[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: int = 0) → None[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
get_jobs(tag: Optional[collections.abc.Hashable] = None) → List[schedule.Job][source]

Gets 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 retrieve
clear(tag: Optional[collections.abc.Hashable] = None) → 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: schedule.Job) → None[source]

Delete a scheduled job.

Parameters:job – The job to be unscheduled
every(interval: int = 1) → schedule.Job[source]

Schedule a new periodic job.

Parameters:interval – A quantity of a certain time unit
Returns:An unconfigured Job
get_next_run(tag: Optional[collections.abc.Hashable] = None) → Optional[datetime.datetime][source]

Datetime when the next job should run.

Parameters:tag – Filter the next run for the given tag parameter
Returns:A datetime object or None if no jobs scheduled
next_run

Datetime when the next job should run.

Parameters:tag – Filter the next run for the given tag parameter
Returns:A datetime object or None if no jobs scheduled
idle_seconds
Returns:Number of seconds until next_run or None if no jobs are scheduled
class schedule.Job(interval: int, scheduler: Optional[schedule.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 identifiers.

Tags must be hashable. Duplicate tags are discarded.

Parameters:tags – A unique list of Hashable tags.
Returns:The invoked job instance
at(time_str: str, tz: Optional[str] = None)[source]

Specify a particular time that the job should be run at.

Parameters:
  • time_str

    A string in one of the following formats:

    • For daily jobs -> HH:MM:SS or HH:MM
    • For hourly jobs -> MM:SS or :MM
    • For minute jobs -> :SS

    The format must make sense given how often the job is repeating; for example, a job that repeats every minute should not be given a string in the form HH:MM:SS. The difference between :MM and :SS is inferred from the selected time-unit (e.g. every().hour.at(‘:30’) vs. every().minute.at(‘:30’)).

  • tz – The timezone that this timestamp refers to. Can be a string that can be parsed by pytz.timezone(), or a pytz.BaseTzInfo object
Returns:

The invoked job instance

to(latest: int)[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
until(until_time: Union[datetime.datetime, datetime.timedelta, datetime.time, str])[source]

Schedule job to run until the specified moment.

The job is canceled whenever the next run is calculated and it turns out the next run is after the until_time. The job is also canceled right before it runs, if the current time is after until_time. This latter case can happen when the the job was scheduled to run before until_time, but runs after until_time.

If until_time is a moment in the past, ScheduleValueError is thrown.

Parameters:until_time

A moment in the future representing the latest time a job can be run. If only a time is supplied, the date is set to today. The following formats are accepted:

  • datetime.datetime
  • datetime.timedelta
  • datetime.time
  • String in one of the following formats: “%Y-%m-%d %H:%M:%S”, “%Y-%m-%d %H:%M”, “%Y-%m-%d”, “%H:%M:%S”, “%H:%M” as defined by strptime() behaviour. If an invalid string format is passed, ScheduleValueError is thrown.
Returns:The invoked job instance
do(job_func: Callable, *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. If the job’s deadline is reached (configured using .until()), the job is not run and CancelJob is returned immediately. If the next scheduled run exceeds the job’s deadline, CancelJob is returned after the execution. In this latter case CancelJob takes priority over any other returned value.

Returns:The return value returned by the job_func, or CancelJob if the job’s deadline is reached.

Exceptions

exception schedule.CancelJob[source]

Can be returned from a job to unschedule itself.