From 93c4393244ba6989c48f8b5f42b2571ec719cef2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alex=20Gr=C3=B6nholm?= Date: Tue, 14 Jun 2016 01:35:11 +0300 Subject: Documented the migration and the scheduler states --- apscheduler/schedulers/base.py | 12 +++++++++--- docs/migration.rst | 14 ++++++++++++-- docs/modules/schedulers/base.rst | 6 +----- 3 files changed, 22 insertions(+), 10 deletions(-) diff --git a/apscheduler/schedulers/base.py b/apscheduler/schedulers/base.py index 2261bd9..72e3c39 100644 --- a/apscheduler/schedulers/base.py +++ b/apscheduler/schedulers/base.py @@ -26,8 +26,11 @@ from apscheduler.events import ( EVENT_JOB_ADDED, EVENT_EXECUTOR_ADDED, EVENT_EXECUTOR_REMOVED, EVENT_ALL_JOBS_REMOVED, EVENT_JOB_SUBMITTED, EVENT_JOB_MAX_INSTANCES, EVENT_SCHEDULER_RESUMED, EVENT_SCHEDULER_PAUSED) +#: constant indicating a scheduler's stopped state STATE_STOPPED = 0 +#: constant indicating a scheduler's running state (started and processing jobs) STATE_RUNNING = 1 +#: constant indicating a scheduler's paused state (started but not processing jobs) STATE_PAUSED = 2 @@ -46,6 +49,9 @@ class BaseScheduler(six.with_metaclass(ABCMeta)): :param dict executors: a dictionary of executor alias -> executor instance or configuration dict + :ivar int state: current running state of the scheduler (one of the following constants from + ``apscheduler.schedulers.base``: ``STATE_STOPPED``, ``STATE_RUNNING``, ``STATE_PAUSED``) + .. seealso:: :ref:`scheduler-config` """ @@ -208,12 +214,12 @@ class BaseScheduler(six.with_metaclass(ABCMeta)): @property def running(self): """ - Return ``True`` if the scheduler has been started and is processing jobs normally. + Return ``True`` if the scheduler has been started. - This is a shortcut for ``scheduler.state == STATE_RUNNING``. + This is a shortcut for ``scheduler.state != STATE_STOPPED``. """ - return self.state == STATE_RUNNING + return self.state != STATE_STOPPED def add_executor(self, executor, alias='default', **executor_opts): """ diff --git a/docs/migration.rst b/docs/migration.rst index ed4f93f..d7bc201 100644 --- a/docs/migration.rst +++ b/docs/migration.rst @@ -2,8 +2,18 @@ Migrating from previous versions of APScheduler ############################################### -From v2.x to 3.0 -================ +From v3.0 to v3.2 +================= + +Prior to v3.1, the scheduler inadvertently exposed the ability to fetch and manipulate jobs before +the scheduler had been started. The scheduler now requires you to call ``scheduler.start()`` before +attempting to access any of the jobs in the job stores. To ensure that no old jobs are mistakenly +executed, you can start the scheduler in paused mode (``scheduler.start(paused=True)``) (introduced +in v3.2) to avoid any premature job processing. + + +From v2.x to v3.0 +================= The 3.0 series is API incompatible with previous releases due to a design overhaul. diff --git a/docs/modules/schedulers/base.rst b/docs/modules/schedulers/base.rst index 7f6c686..fecacca 100644 --- a/docs/modules/schedulers/base.rst +++ b/docs/modules/schedulers/base.rst @@ -2,9 +2,5 @@ ================================== .. automodule:: apscheduler.schedulers.base - -API ---- - -.. autoclass:: BaseScheduler :members: + :member-order: bysource -- cgit v1.2.1