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. Any extra keyword arguments are passed along to the constructor of the Job class (see Job options).

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. Any extra keyword arguments are passed along to the constructor of the Job class (see Job options).

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. Any extra keyword arguments are passed along to the constructor of the Job class (see Job options).

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. Any extra keyword arguments are passed along to the constructor of the Job class (see Job options).

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(). Any extra keyword arguments are passed along to the constructor of the Job class (see Job options).

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(). Any extra keyword arguments are passed along to the constructor of the Job class (see Job options).

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:closeTrue 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:
  • waitTrue to wait until all currently executing jobs have finished (if shutdown_threadpool is also True)
  • shutdown_threadpoolTrue to shut down the thread pool
  • close_jobstoresTrue to close all job stores after shutdown
start()

Starts the scheduler in a new thread.

In threaded mode (the default), this method will return immediately after starting the scheduler thread.

In standalone mode, this method will block until there are no more scheduled jobs.

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.