Reference¶
This part of the documentation covers all the interfaces of schedule.
Main Interface¶
-
schedule.
every
(interval: int = 1) → schedule.Job[source]¶ Calls
every
on thedefault scheduler instance
.
-
schedule.
run_pending
() → None[source]¶ Calls
run_pending
on thedefault scheduler instance
.
-
schedule.
run_all
(delay_seconds: int = 0) → None[source]¶ Calls
run_all
on thedefault scheduler instance
.
-
schedule.
get_jobs
(tag: Optional[collections.abc.Hashable] = None) → List[schedule.Job][source]¶ Calls
get_jobs
on thedefault scheduler instance
.
-
schedule.
clear
(tag: Optional[collections.abc.Hashable] = None) → None[source]¶ Calls
clear
on thedefault scheduler instance
.
-
schedule.
cancel_job
(job: schedule.Job) → None[source]¶ Calls
cancel_job
on thedefault scheduler instance
.
-
schedule.
next_run
(tag: Optional[collections.abc.Hashable] = None) → Optional[datetime.datetime][source]¶ Calls
next_run
on thedefault scheduler instance
.
-
schedule.
idle_seconds
() → Optional[float][source]¶ Calls
idle_seconds
on thedefault 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
-
-
class
schedule.
Job
(interval: int, scheduler: Optional[schedule.Scheduler] = None)[source]¶ A periodic job as used by
Scheduler
.Parameters: 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
- time_str –
-
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.
- a