1############################################### 2Migrating from previous versions of APScheduler 3############################################### 4 5From v3.0 to v3.2 6================= 7 8Prior to v3.1, the scheduler inadvertently exposed the ability to fetch and manipulate jobs before 9the scheduler had been started. The scheduler now requires you to call ``scheduler.start()`` before 10attempting to access any of the jobs in the job stores. To ensure that no old jobs are mistakenly 11executed, you can start the scheduler in paused mode (``scheduler.start(paused=True)``) (introduced 12in v3.2) to avoid any premature job processing. 13 14 15From v2.x to v3.0 16================= 17 18The 3.0 series is API incompatible with previous releases due to a design overhaul. 19 20Scheduler changes 21----------------- 22 23* The concept of "standalone mode" is gone. For ``standalone=True``, use 24 :class:`~apscheduler.schedulers.blocking.BlockingScheduler` instead, and for 25 ``standalone=False``, use :class:`~apscheduler.schedulers.background.BackgroundScheduler`. 26 BackgroundScheduler matches the old default semantics. 27* Job defaults (like ``misfire_grace_time`` and ``coalesce``) must now be passed in a dictionary as 28 the ``job_defaults`` option to :meth:`~apscheduler.schedulers.base.BaseScheduler.configure`. When 29 supplying an ini-style configuration as the first argument, they will need a corresponding 30 ``job_defaults.`` prefix. 31* The configuration key prefix for job stores was changed from ``jobstore.`` to ``jobstores.`` to 32 match the dict-style configuration better. 33* The ``max_runs`` option has been dropped since the run counter could not be reliably preserved 34 when replacing a job with another one with the same ID. To make up for this, the ``end_date`` 35 option was added to cron and interval triggers. 36* The old thread pool is gone, replaced by ``ThreadPoolExecutor``. 37 This means that the old ``threadpool`` options are no longer valid. 38 See :ref:`scheduler-config` on how to configure executors. 39* The trigger-specific scheduling methods have been removed entirely from the scheduler. 40 Use the generic :meth:`~apscheduler.schedulers.base.BaseScheduler.add_job` method or the 41 :meth:`~apscheduler.schedulers.base.BaseScheduler.scheduled_job` decorator instead. 42 The signatures of these methods were changed significantly. 43* The ``shutdown_threadpool`` and ``close_jobstores`` options have been removed from the 44 :meth:`~apscheduler.schedulers.base.BaseScheduler.shutdown` method. 45 Executors and job stores are now always shut down on scheduler shutdown. 46* :meth:`~apscheduler.scheduler.Scheduler.unschedule_job` and 47 :meth:`~apscheduler.scheduler.Scheduler.unschedule_func` have been replaced by 48 :meth:`~apscheduler.schedulers.base.BaseScheduler.remove_job`. You can also unschedule a job by 49 using the job handle returned from :meth:`~apscheduler.schedulers.base.BaseScheduler.add_job`. 50 51Job store changes 52----------------- 53 54The job store system was completely overhauled for both efficiency and forwards compatibility. 55Unfortunately, this means that the old data is not compatible with the new job stores. 56If you need to migrate existing data from APScheduler 2.x to 3.x, contact the APScheduler author. 57 58The Shelve job store had to be dropped because it could not support the new job store design. 59Use SQLAlchemyJobStore with SQLite instead. 60 61Trigger changes 62--------------- 63 64From 3.0 onwards, triggers now require a pytz timezone. This is normally provided by the scheduler, 65but if you were instantiating triggers manually before, then one must be supplied as the 66``timezone`` argument. 67 68The only other backwards incompatible change was that ``get_next_fire_time()`` takes two arguments 69now: the previous fire time and the current datetime. 70 71 72From v1.x to 2.0 73================ 74 75There have been some API changes since the 1.x series. This document 76explains the changes made to v2.0 that are incompatible with the v1.x API. 77 78API changes 79----------- 80 81* The behavior of cron scheduling with regards to default values for omitted 82 fields has been made more intuitive -- omitted fields lower than the least 83 significant explicitly defined field will default to their minimum values 84 except for the week number and weekday fields 85* SchedulerShutdownError has been removed -- jobs are now added tentatively 86 and scheduled for real when/if the scheduler is restarted 87* Scheduler.is_job_active() has been removed -- use 88 ``job in scheduler.get_jobs()`` instead 89* dump_jobs() is now print_jobs() and prints directly to the given file or 90 sys.stdout if none is given 91* The ``repeat`` parameter was removed from 92 :meth:`~apscheduler.scheduler.Scheduler.add_interval_job` and 93 :meth:`~apscheduler.scheduler.Scheduler.interval_schedule` in favor of the 94 universal ``max_runs`` option 95* :meth:`~apscheduler.scheduler.Scheduler.unschedule_func` now raises a 96 KeyError if the given function is not scheduled 97* The semantics of :meth:`~apscheduler.scheduler.Scheduler.shutdown` have 98 changed -- the method no longer accepts a numeric argument, but two booleans 99 100 101Configuration changes 102--------------------- 103 104* The scheduler can no longer be reconfigured while it's running 105