diff options
author | Alex Grönholm <alex.gronholm@nextday.fi> | 2014-05-28 13:04:04 +0300 |
---|---|---|
committer | Alex Grönholm <alex.gronholm@nextday.fi> | 2014-05-29 09:05:05 +0300 |
commit | e86bd098138a1432bb3f1b6dce7fa913eb9ed2f3 (patch) | |
tree | 44bbe4c01ffdb9d7f8475a26d7e23e4b2ac5b7af /docs/index.rst | |
parent | e5e2c7f979fea4c2109094943b04259841f207cf (diff) | |
download | apscheduler-e86bd098138a1432bb3f1b6dce7fa913eb9ed2f3.tar.gz |
Revised the rest of the documentation
Diffstat (limited to 'docs/index.rst')
-rw-r--r-- | docs/index.rst | 436 |
1 files changed, 11 insertions, 425 deletions
diff --git a/docs/index.rst b/docs/index.rst index cbfc5b7..81d42ed 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,438 +1,24 @@ Advanced Python Scheduler ========================= -.. contents:: - -Introduction ------------- - -Advanced Python Scheduler (APScheduler) is a light but powerful in-process task -scheduler that lets you schedule functions (or any other python callables) to be -executed at times of your choosing. - -This can be a far better alternative to externally run cron scripts for -long-running applications (e.g. web applications), as it is platform neutral -and can directly access your application's variables and functions. - -The development of APScheduler was heavily influenced by the `Quartz -<http://www.quartz-scheduler.org/>`_ task scheduler written in Java. -APScheduler provides most of the major features that Quartz does, but it also -provides features not present in Quartz (such as multiple job stores). - - -Features --------- - .. include:: ../README.rst - :start-after: Features - ======== :end-before: Documentation - ============= - -Usage -===== - -Installing APScheduler ----------------------- - -The preferred installation method is by using `pip <http://pypi.python.org/pypi/pip/>`_:: - - $ pip install apscheduler - -or `easy_install <http://pypi.python.org/pypi/distribute/>`_:: - - $ easy_install apscheduler - -If that doesn't work, you can manually `download the APScheduler distribution -<http://pypi.python.org/pypi/APScheduler/>`_ from PyPI, extract and then -install it:: - $ python setup.py install - -Starting the scheduler ----------------------- - -To start the scheduler with default settings:: - - from apscheduler.scheduler import Scheduler - - sched = Scheduler() - sched.start() - -The constructor takes as its first, optional parameter a dictionary of "global" -options to facilitate configuration from .ini files. All APScheduler options -given in the global configuration must begin with "apscheduler." to avoid name -clashes with other software. The constructor also takes options as keyword -arguments (without the prefix). - -You can also configure the scheduler after its instantiation, if necessary. -This is handy if you use the decorators for scheduling and must have a -Scheduler instance available from the very beginning:: - - from apscheduler.scheduler import Scheduler - - sched = Scheduler() - - @sched.scheduled_job('interval', {'hours': 3}) - def some_job(): - print "Decorated job" - - sched.configure(options_from_ini_file) - sched.start() - - -Scheduling jobs ---------------- - -The simplest way to schedule jobs using the built-in triggers is to use one of -the shortcut methods provided by the scheduler: +Table of Contents +================= .. toctree:: - :maxdepth: 1 - - dateschedule - intervalschedule - cronschedule - -These shortcuts cover the vast majority of use cases. However, if you need -to use a custom trigger, you need to use the -:meth:`~apscheduler.scheduler.Scheduler.add_job` method. - -When a scheduled job is triggered, it is handed over to the thread pool for -execution. - -You can request a job to be added to a specific job store by giving the target -job store's alias in the ``jobstore`` option to -:meth:`~apscheduler.scheduler.Scheduler.add_job` or any of the above shortcut -methods. - -You can schedule jobs on the scheduler **at any time**. If the scheduler is not -running when the job is added, the job will be scheduled `tentatively` and its -first run time will only be computed when the scheduler starts. Jobs will not -run retroactively in such cases. - -.. warning:: Scheduling new jobs from existing jobs is not currently reliable. - This will likely be fixed in the next major release. - - -.. _job_options: - -Job options ------------ - -The following options can be given as keyword arguments to -:meth:`~apscheduler.scheduler.Scheduler.add_job` or one of the shortcut -methods, including the decorators. - -===================== ========================================================= -Option Definition -===================== ========================================================= -name Name of the job (informative, does not have to be unique) -misfire_grace_time Time in seconds that the job is allowed to miss the the - designated run time before being considered to have - misfired (see :ref:`coalescing`) - (overrides the global scheduler setting) -coalesce Run once instead of many times if the scheduler - determines that the job should be run more than once in - succession (see :ref:`coalescing`) - (overrides the global scheduler setting) -max_runs Maximum number of times this job is allowed to be - triggered before being removed -max_instances Maximum number of concurrently running instances allowed - for this job (see :ref:`_max_instances`) -===================== ========================================================= - - -Shutting down the scheduler ---------------------------- - -To shut down the scheduler:: - - sched.shutdown() - -By default, the scheduler shuts down its thread pool and waits until all -currently executing jobs are finished. For a faster exit you can do:: - - sched.shutdown(wait=False) - -This will still shut down the thread pool but does not wait for any running -tasks to complete. Also, if you gave the scheduler a thread pool that you want -to manage elsewhere, you probably want to skip the thread pool shutdown -altogether:: - - sched.shutdown(shutdown_threadpool=False) - -This implies ``wait=False``, since there is no way to wait for the scheduler's -tasks to finish without shutting down the thread pool. - -A neat trick to automatically shut down the scheduler is to use an :py:mod:`atexit` -hook for that:: - - import atexit - - sched = Scheduler(daemon=True) - atexit.register(lambda: sched.shutdown(wait=False)) - # Proceed with starting the actual application - - -Scheduler configuration options -------------------------------- - -======================= ========== ============================================== -Directive Default Definition -======================= ========== ============================================== -misfire_grace_time 1 Maximum time in seconds for the job execution - to be allowed to delay before it is considered - a misfire (see :ref:`coalescing`) -coalesce False Roll several pending executions of jobs into one - (see :ref:`coalescing`) -standalone False If set to ``True``, - :meth:`~apscheduler.scheduler.Scheduler.start` - will run the main loop in the calling - thread until no more jobs are scheduled. - See :ref:`modes` for more information. -daemonic True Controls whether the scheduler thread is - daemonic or not. This option has no effect when - ``standalone`` is ``True``. - - If set to ``False``, then the - scheduler must be shut down explicitly - when the program is about to finish, or it will - prevent the program from terminating. - - If set to ``True``, the scheduler will - automatically terminate with the application, - but may cause an exception to be raised on - exit. - - Jobs are always executed in non-daemonic - threads. -threadpool (built-in) Instance of a :pep:`3148` compliant thread - pool or a dot-notation (``x.y.z:varname``) - reference to one -threadpool.core_threads 0 Maximum number of persistent threads in the pool -threadpool.max_threads 20 Maximum number of total threads in the pool -threadpool.keepalive 1 Seconds to keep non-core worker threads waiting - for new tasks -jobstores.X.class Class of the jobstore named X (specified as - module.name:classname) -jobstores.X.Y Constructor option Y of jobstore X -======================= ========== ============================================== - - -.. _modes: - -Operating modes: embedded vs standalone ---------------------------------------- - -The scheduler has two operating modes: standalone and embedded. In embedded mode, -it will spawn its own thread when :meth:`~apscheduler.scheduler.Scheduler.start` -is called. In standalone mode, it will run directly in the calling thread and -will block until there are no more pending jobs. - -The embedded mode is suitable for running alongside some application that requires -scheduling capabilities. The standalone mode, on the other hand, can be used as a -handy cross-platform cron replacement for executing Python code. A typical usage -of the standalone mode is to have a script that only adds the jobs to the scheduler -and then calls :meth:`~apscheduler.scheduler.Scheduler.start` on the scheduler. - -All of the examples in the examples directory demonstrate usage of the standalone -mode, with the exception of ``threaded.py`` which demonstrates the embedded mode -(where the "application" just prints a line every 2 seconds). - - -Job stores ----------- - -APScheduler keeps all the scheduled jobs in *job stores*. Job stores are -configurable adapters to some back-end that may or may not support persisting -job configurations on disk, database or something else. Job stores are added -to the scheduler and identified by their aliases. The alias ``default`` is -special in that if the user does not explicitly specify a job store alias when -scheduling a job, it goes to the ``default`` job store. If there is no job -store in the scheduler by that name when the scheduler is started, a new job -store of type :class:`~apscheduler.jobstores.ram_store.RAMJobStore` is created -to serve as the default. - -The other built-in job stores are: - -* :class:`~apscheduler.jobstores.shelve_store.ShelveJobStore` -* :class:`~apscheduler.jobstores.sqlalchemy_store.SQLAlchemyJobStore` -* :class:`~apscheduler.jobstores.mongodb_store.MongoDBJobStore` -* :class:`~apscheduler.jobstores.redis_store.RedisJobStore` - -Job stores can be added either through configuration options or the -:meth:`~apscheduler.scheduler.Scheduler.add_jobstore` method. The following -are therefore equal:: - - config = {'apscheduler.jobstore.file.class': 'apscheduler.jobstores.shelve_store:ShelveJobStore', - 'apscheduler.jobstore.file.path': '/tmp/dbfile'} - sched = Scheduler(config) - -and:: - - from apscheduler.jobstores.shelve_store import ShelveJobStore - - sched = Scheduler() - sched.add_jobstore(ShelveJobStore('/tmp/dbfile'), 'file') - -The example configuration above results in the scheduler having two -job stores -- one -:class:`~apscheduler.jobstores.ram_store.RAMJobStore` and one -:class:`~apscheduler.jobstores.shelve_store.ShelveJobStore`. - - -Job persistency ---------------- - -The built-in job stores (other than -:class:`~apscheduler.jobstores.ram_store.RAMJobStore`) store jobs in a durable -manner. This means that when you schedule jobs in them, shut down the scheduler, -restart it and readd the job store in question, it will load the previously -scheduled jobs automatically. - -Persistent job stores store a reference to the target callable in text form -and serialize the arguments using pickle. This unfortunately adds some -restrictions: - -* You cannot schedule static methods, inner functions or lambdas. -* You cannot update the objects given as arguments to the callable. - -Technically you *can* update the state of the argument objects, but those -changes are never persisted back to the job store. - -.. note:: None of these restrictions apply to ``RAMJobStore``. - - -.. _max_instances: - -Limiting the number of concurrently executing instances of a job ----------------------------------------------------------------- - -By default, no two instances of the same job will be run concurrently. This -means that if the job is about to be run but the previous run hasn't finished -yet, then the latest run is considered a misfire. It is possible to set the -maximum number of instances for a particular job that the scheduler will let -run concurrently, by using the ``max_instances`` keyword argument when adding -the job. - - -.. _coalescing: - -Missed job executions and coalescing ------------------------------------- - -Sometimes the scheduler may be unable to execute a scheduled job at the time -it was scheduled to run. The most common case is when a job is scheduled in a -persistent job store and the scheduler is shut down and restarted after the job -was supposed to execute. When this happens, the job is considered to have -"misfired". The scheduler will then check each missed execution time against -the job's ``misfire_grace_time`` option (which can be set on per-job basis or -globally in the scheduler) to see if the execution should still be triggered. -This can lead into the job being executed several times in succession. - -If this behavior is undesirable for your particular use case, it is possible -to use `coalescing` to roll all these missed executions into one. In other -words, if coalescing is enabled for the job and the scheduler sees one or more -queued executions for the job, it will only trigger it once. The "bypassed" -runs of the job are not considered misfires nor do they count towards any -maximum run count of the job. - - -Scheduler events ----------------- - -It is possible to attach event listeners to the scheduler. Scheduler events are -fired on certain occasions, and may carry additional information in them -concerning the details of that particular event. It is possible to listen to -only particular types of events by giving the appropriate ``mask`` argument to -:meth:`~apscheduler.scheduler.Scheduler.add_listener`, OR'ing -the different constants together. The listener callable is called with one -argument, the event object. The type of the event object is tied to the event -code as shown below: - -========================== ============== ========================================== -Constant Event class Triggered when... -========================== ============== ========================================== -EVENT_SCHEDULER_START SchedulerEvent The scheduler is started -EVENT_SCHEDULER_SHUTDOWN SchedulerEvent The scheduler is shut down -EVENT_JOBSTORE_ADDED JobStoreEvent A job store is added to the scheduler -EVENT_JOBSTORE_REMOVED JobStoreEvent A job store is removed from the scheduler -EVENT_JOBSTORE_JOB_ADDED JobStoreEvent A job is added to a job store -EVENT_JOBSTORE_JOB_REMOVED JobStoreEvent A job is removed from a job store -EVENT_JOB_EXECUTED JobEvent A job is executed successfully -EVENT_JOB_ERROR JobEvent A job raised an exception during execution -EVENT_JOB_MISSED JobEvent A job's execution time is missed -========================== ============== ========================================== - -See the documentation for the :mod:`~apscheduler.events` module for specifics -on the available event attributes. - -Example:: - - def my_listener(event): - if event.exception: - print 'The job crashed :(' - else: - print 'The job worked :)' - - scheduler.add_listener(my_listener, EVENT_JOB_EXECUTED | EVENT_JOB_ERROR) - - -Getting a list of scheduled jobs --------------------------------- - -If you want to see which jobs are currently added in the scheduler, you can -simply do:: - - sched.print_jobs() - -This will print a human-readable listing of scheduled jobs, their triggering -mechanisms and the next time they will fire. If you supply a file-like object -as an argument to this method, it will output the results in that file. - -To get a machine processable list of the scheduled jobs, you can use the -:meth:`~apscheduler.scheduler.Scheduler.get_jobs` scheduler method. It will -return a list of :class:`~apscheduler.job.Job` instances. - - -Extending APScheduler -===================== - -It is possible to extend APScheduler to support alternative job stores and -triggers. See the :doc:`Extending APScheduler <extending>` document for details. - - -FAQ -=== - -Q: Why do my processes hang instead of exiting when they are finished? - -A: A scheduled job may still be executing. APScheduler's thread pool is wired -to wait for the job threads to exit before allowing the interpreter to exit to -avoid unpredictable behavior caused by the shutdown procedures of the Python -interpreter. A more thorough explanation -`can be found here <http://joeshaw.org/2009/02/24/605>`_. - - -Reporting bugs -============== - -A `bug tracker <http://bitbucket.org/agronholm/apscheduler/issues/>`_ -is provided by bitbucket.org. - - -Getting help -============ - -If you have problems or other questions, you can either: + :maxdepth: 1 -* Ask on the `APScheduler Google group - <http://groups.google.com/group/apscheduler>`_, or -* Ask on the ``#apscheduler`` channel on - `Freenode IRC <http://freenode.net/irc_servers.shtml>`_ + userguide + versionhistory + migration + contributing + extending -.. include:: ../CHANGES.rst +Indices and tables +================== +* :ref:`API reference <modindex>` |