apscheduler.scheduler

This module is the main part of the library. It houses the Scheduler class and related exceptions.

Module Contents

class apscheduler.scheduler.Scheduler(gconfig={}, **options)

This class is responsible for scheduling jobs and triggering their execution.

add_cron_job(func, year=None, month=None, day=None, week=None, day_of_week=None, hour=None, minute=None, second=None, start_date=None, args=None, kwargs=None, **options)

Schedules a job to be completed on times that match the given expressions.

Parameters:

• func – callable to run
• year – year to run on
• month – month to run on
• day – day of month to run on
• week – week of the year to run on
• day_of_week – weekday to run on (0 = Monday)
• hour – hour to run on
• second – second to run on
• args – list of positional arguments to call func with
• kwargs – dict of keyword arguments to call func with
• name – name of the job
• jobstore – alias of the job store to add the job to
• misfire_grace_time – seconds after the designated run time that the job is still allowed to be run

Returns:

the scheduled job

Return type:

Job

add_date_job(func, date, args=None, kwargs=None, **options)

Schedules a job to be completed on a specific date and time.

Parameters:

• func – callable to run at the given time
• date (datetime.date) – the date/time to run the job at
• name – name of the job
• jobstore – stored the job in the named (or given) job store
• misfire_grace_time – seconds after the designated run time that the job is still allowed to be run

Return type:

Job

add_interval_job(func, weeks=0, days=0, hours=0, minutes=0, seconds=0, start_date=None, args=None, kwargs=None, **options)

Schedules a job to be completed on specified intervals.

Parameters:

• func – callable to run
• weeks – number of weeks to wait
• days – number of days to wait
• hours – number of hours to wait
• minutes – number of minutes to wait
• seconds – number of seconds to wait
• start_date – when to first execute the job and start the counter (default is after the given interval)
• args – list of positional arguments to call func with
• kwargs – dict of keyword arguments to call func with
• name – name of the job
• jobstore – alias of the job store to add the job to
• misfire_grace_time – seconds after the designated run time that the job is still allowed to be run

Return type:

Job

add_job(trigger, func, args, kwargs, jobstore='default', **options)

Adds the given job to the job list and notifies the scheduler thread.

Parameters:

• trigger – trigger that determines when func is called
• func – callable to run at the given time
• args – list of positional arguments to call func with
• kwargs – dict of keyword arguments to call func with
• jobstore – alias of the job store to store the job in

Return type:

Job

add_jobstore(jobstore, alias, quiet=False)

Adds a job store to this scheduler.

Parameters:

• jobstore (instance of JobStore) – job store to be added
• alias (str) – alias for the job store
• quiet – True to suppress scheduler thread wakeup

add_listener(callback, mask=511)

Adds a listener for scheduler events. When a matching event occurs, callback is executed with the event object as its sole argument. If the mask parameter is not provided, the callback will receive events of all types.

Parameters:

• callback – any callable that takes one argument
• mask – bitmask that indicates which events should be listened to

configure(gconfig={}, **options)

Reconfigures the scheduler with the given options. Can only be done when the scheduler isn’t running.

cron_schedule(**options)

Decorator version of add_cron_job(). This decorator does not wrap its host function. Unscheduling decorated functions is possible by passing the job attribute of the scheduled function to unschedule_job().

get_jobs()

Returns a list of all scheduled jobs.

Returns:list of Job objects

interval_schedule(**options)

Decorator version of add_interval_job(). This decorator does not wrap its host function. Unscheduling decorated functions is possible by passing the job attribute of the scheduled function to unschedule_job().

print_jobs(out=None)

Prints out a textual listing of all jobs currently scheduled on this scheduler.

Parameters:out – a file-like object to print to (defaults to sys.stdout if nothing is given)

remove_jobstore(alias, close=True)

Removes the job store by the given alias from this scheduler.

Parameters:close – True to close the job store after removing it

remove_listener(callback)

Removes a previously added event listener.

shutdown(wait=True, shutdown_threadpool=True, close_jobstores=True)

Shuts down the scheduler and terminates the thread. Does not interrupt any currently running jobs.

Parameters:

• wait – True to wait until all currently executing jobs have finished (if shutdown_threadpool is also True)
• shutdown_threadpool – True to shut down the thread pool
• close_jobstores – True to close all job stores after shutdown

start()

Starts the scheduler in a new thread.

unschedule_func(func)

Removes all jobs that would execute the given function.

unschedule_job(job)

Removes a job, preventing it from being run any more.

exception apscheduler.scheduler.SchedulerAlreadyRunningError

Raised when attempting to start or configure the scheduler when it’s already running.