Fixed a number of errors in the documentation and type annotations

docs/api.rst

@@ -8,7 +8,6 @@ Data structures
 .. autoclass:: apscheduler.Schedule
 .. autoclass:: apscheduler.Job
 .. autoclass:: apscheduler.JobResult
-.. autoclass:: apscheduler.RetrySettings
 
 Schedulers
 ----------
@@ -31,13 +30,13 @@ Data stores
 .. autoclass:: apscheduler.abc.DataStore
 .. autoclass:: apscheduler.datastores.memory.MemoryDataStore
 .. autoclass:: apscheduler.datastores.sqlalchemy.SQLAlchemyDataStore
-.. autoclass:: apscheduler.datastores.async_sqlalchemy.AsyncSQLAlchemyDataStore
 .. autoclass:: apscheduler.datastores.mongodb.MongoDBDataStore
 
 Event brokers
 -------------
 
 .. autoclass:: apscheduler.abc.EventBroker
+.. autoclass:: apscheduler.abc.Subscription
 .. autoclass:: apscheduler.eventbrokers.local.LocalEventBroker
 .. autoclass:: apscheduler.eventbrokers.asyncpg.AsyncpgEventBroker
 .. autoclass:: apscheduler.eventbrokers.mqtt.MQTTEventBroker
@@ -88,22 +87,40 @@ Events
 Enumerated types
 ----------------
 
-.. autoclass:: apscheduler.RunState
-.. autoclass:: apscheduler.JobOutcome
-.. autoclass:: apscheduler.ConflictPolicy
-.. autoclass:: apscheduler.CoalescePolicy
+.. autoclass:: apscheduler.SchedulerRole()
+    :show-inheritance:
+
+.. autoclass:: apscheduler.RunState()
+    :show-inheritance:
+
+.. autoclass:: apscheduler.JobOutcome()
+    :show-inheritance:
+
+.. autoclass:: apscheduler.ConflictPolicy()
+    :show-inheritance:
+
+.. autoclass:: apscheduler.CoalescePolicy()
+    :show-inheritance:
 
 Context variables
 -----------------
 
 See the :mod:`contextvars` module for information on how to work with context variables.
 
 .. data:: apscheduler.current_scheduler
-   :annotation: the current scheduler
-   :type: ~contextvars.ContextVar[~typing.Union[Scheduler, AsyncScheduler]]
+   :type: ~contextvars.ContextVar[Scheduler]
+
+   The current scheduler.
+
+.. data:: apscheduler.current_async_scheduler
+   :type: ~contextvars.ContextVar[AsyncScheduler]
+
+   The current asynchronous scheduler.
+
 .. data:: apscheduler.current_job
-   :annotation: information on the job being currently run
-   :type: ~contextvars.ContextVar[JobInfo]
+   :type: ~contextvars.ContextVar[Job]
+
+   The job being currently run (available when running the job's target callable).
 
 Exceptions
 ----------
@@ -118,3 +135,9 @@ Exceptions
 .. autoexception:: apscheduler.SerializationError
 .. autoexception:: apscheduler.DeserializationError
 .. autoexception:: apscheduler.MaxIterationsReached
+
+Support classes for retrying failures
+-------------------------------------
+
+.. autoclass:: apscheduler.RetrySettings
+.. autoclass:: apscheduler.RetryMixin

docs/conf.py

@@ -44,7 +44,16 @@
 exclude_patterns = []
 
 autodoc_default_options = {"members": True}
-autodoc_mock_imports = ["asyncpg", "cbor2", "paho", "pymongo", "redis", "sqlalchemy"]
+autodoc_mock_imports = [
+    "asyncpg",
+    "bson",
+    "cbor2",
+    "paho",
+    "pymongo",
+    "redis",
+    "sqlalchemy",
+    "PyQt6",
+]
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -55,7 +64,6 @@
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
-    "sqlalchemy": ("https://docs.sqlalchemy.org/en/20/", None),
     "anyio": ("https://anyio.readthedocs.io/en/latest/", None),
-    "cbor2": ("https://cbor2.readthedocs.io/en/latest/", None),
+    "tenacity": ("https://tenacity.readthedocs.io/en/latest/", None),
 }

docs/integrations.rst

@@ -1,6 +1,8 @@
 Integrating with application frameworks
 =======================================
 
+.. py:currentmodule:: apscheduler
+
 WSGI
 ----
 
@@ -37,7 +39,7 @@ by default which then prevents the scheduler from working. See the
 `uWSGI documentation <uWSGI-threads>`_ for more details.
 
 .. note::
-    The :meth:`.schedulers.Scheduler.start_in_background` method installs an
+    The :meth:`Scheduler.start_in_background` method installs an
     :mod:`atexit` hook that shuts down the scheduler gracefully when the worker process
     exits.
 

docs/migration.rst

@@ -52,18 +52,16 @@ Scheduler changes
 -----------------
 
 The ``add_job()`` method is now :meth:`~Scheduler.add_schedule`. The scheduler still has
-a method named :meth:`~Scheduler.add_job`, but this is meant for making one-off runs of a
-task. Previously you would have had to call ``add_job()`` with a
-:class:`~apscheduler.triggers.date.DateTrigger` using the current time as the run time.
+a method named :meth:`~Scheduler.add_job`, but this is meant for making one-off runs of
+a task. Previously you would have had to call ``add_job()`` with a
+:class:`~triggers.date.DateTrigger` using the current time as the run time.
 
 The two most commonly used schedulers, ``BlockingScheduler`` and
 ``BackgroundScheduler``, have often caused confusion among users and have thus been
-combined into :class:`~.schedulers.Scheduler`. This new unified scheduler class
-has two methods that replace the ``start()`` method used previously:
-:meth:`~.schedulers.Scheduler.run_until_stopped` and
-:meth:`~.schedulers.Scheduler.start_in_background`. The former should be used if
-you previously used ``BlockingScheduler``, and the latter if you used
-``BackgroundScheduler``.
+combined into :class:`~Scheduler`. This new unified scheduler class has two methods that
+replace the ``start()`` method used previously: :meth:`~Scheduler.run_until_stopped` and
+:meth:`~Scheduler.start_in_background`. The former should be used if you previously used
+``BlockingScheduler``, and the latter if you used ``BackgroundScheduler``.
 
 The asyncio scheduler has been replaced with a more generic :class:`AsyncScheduler`,
 which is based on AnyIO_ and thus also supports Trio_ in addition to :mod:`asyncio`.
@@ -98,12 +96,12 @@ documentation for more information.
 This not only simplified trigger design, but also enabled the scheduler to provide
 information about the randomized jitter and the original run time to the user.
 
-:class:`~.triggers.cron.CronTrigger` was changed to respect the standard order of
+:class:`~triggers.cron.CronTrigger` was changed to respect the standard order of
 weekdays, so that Sunday is now 0 and Saturday is 6. If you used numbered weekdays
 before, you must change your trigger configuration to match. If in doubt, use
 abbreviated weekday names (e.g. ``sun``, ``fri``) instead.
 
-:class:`~.triggers.interval.IntervalTrigger` was changed to start immediately, instead
+:class:`~triggers.interval.IntervalTrigger` was changed to start immediately, instead
 of waiting for the first interval to pass. If you have workarounds in place to "fix"
 the previous behavior, you should remove them.
 
@@ -112,11 +110,12 @@ the previous behavior, you should remove them.
 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.
+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
@@ -128,52 +127,50 @@ Scheduler changes
 -----------------
 
 * The concept of "standalone mode" is gone. For ``standalone=True``, use
-  :class:`~apscheduler.schedulers.blocking.BlockingScheduler` instead, and for
-  ``standalone=False``, use :class:`~apscheduler.schedulers.background.BackgroundScheduler`.
-  BackgroundScheduler matches the old default semantics.
-* Job defaults (like ``misfire_grace_time`` and ``coalesce``) must now be passed in a dictionary as
-  the ``job_defaults`` option to :meth:`~apscheduler.schedulers.base.BaseScheduler.configure`. When
-  supplying an ini-style configuration as the first argument, they will need a corresponding
-  ``job_defaults.`` prefix.
-* The configuration key prefix for job stores was changed from ``jobstore.`` to ``jobstores.`` to
-  match the dict-style configuration better.
-* The ``max_runs`` option has been dropped since the run counter could not be reliably preserved
-  when replacing a job with another one with the same ID. To make up for this, the ``end_date``
-  option was added to cron and interval triggers.
+  ``BlockingScheduler`` instead, and for ``standalone=False``, use
+  ``BackgroundScheduler``. BackgroundScheduler matches the old default semantics.
+* Job defaults (like ``misfire_grace_time`` and ``coalesce``) must now be passed in a
+  dictionary as the ``job_defaults`` option to ``BaseScheduler.configure()``. When
+  supplying an ini-style configuration as the first argument, they will need a
+  corresponding ``job_defaults.`` prefix.
+* The configuration key prefix for job stores was changed from ``jobstore.`` to
+  ``jobstores.`` to match the dict-style configuration better.
+* The ``max_runs`` option has been dropped since the run counter could not be reliably
+  preserved when replacing a job with another one with the same ID. To make up for this,
+  the ``end_date`` option was added to cron and interval triggers.
 * The old thread pool is gone, replaced by ``ThreadPoolExecutor``.
   This means that the old ``threadpool`` options are no longer valid.
-  See :ref:`scheduler-config` on how to configure executors.
 * The trigger-specific scheduling methods have been removed entirely from the scheduler.
-  Use the generic :meth:`~apscheduler.schedulers.base.BaseScheduler.add_job` method or the
-  :meth:`~apscheduler.schedulers.base.BaseScheduler.scheduled_job` decorator instead.
-  The signatures of these methods were changed significantly.
+  Use the generic ``BaseScheduler.add_job()`` method or the
+  ``@BaseScheduler.scheduled_job`` decorator instead. The signatures of these methods
+  were changed significantly.
 * The ``shutdown_threadpool`` and ``close_jobstores`` options have been removed from the
-  :meth:`~apscheduler.schedulers.base.BaseScheduler.shutdown` method.
+  ``BaseScheduler.shutdown()`` method.
   Executors and job stores are now always shut down on scheduler shutdown.
-* :meth:`~apscheduler.scheduler.Scheduler.unschedule_job` and
-  :meth:`~apscheduler.scheduler.Scheduler.unschedule_func` have been replaced by
-  :meth:`~apscheduler.schedulers.base.BaseScheduler.remove_job`. You can also unschedule a job by
-  using the job handle returned from :meth:`~apscheduler.schedulers.base.BaseScheduler.add_job`.
+* ``Scheduler.unschedule_job()`` and ``Scheduler.unschedule_func()`` have been replaced
+  by ``BaseScheduler.remove_job()``. You can also unschedule a job by using the job
+  handle returned from ``BaseScheduler.add_job()``.
 
 Job store changes
 -----------------
 
-The job store system was completely overhauled for both efficiency and forwards compatibility.
-Unfortunately, this means that the old data is not compatible with the new job stores.
-If you need to migrate existing data from APScheduler 2.x to 3.x, contact the APScheduler author.
+The job store system was completely overhauled for both efficiency and forwards
+compatibility. Unfortunately, this means that the old data is not compatible with the
+new job stores. If you need to migrate existing data from APScheduler 2.x to 3.x,
+contact the APScheduler author.
 
-The Shelve job store had to be dropped because it could not support the new job store design.
-Use SQLAlchemyJobStore with SQLite instead.
+The Shelve job store had to be dropped because it could not support the new job store
+design. Use SQLAlchemyJobStore with SQLite instead.
 
 Trigger changes
 ---------------
 
-From 3.0 onwards, triggers now require a pytz timezone. This is normally provided by the scheduler,
-but if you were instantiating triggers manually before, then one must be supplied as the
-``timezone`` argument.
+From 3.0 onwards, triggers now require a pytz timezone. This is normally provided by the
+scheduler, but if you were instantiating triggers manually before, then one must be
+supplied as the ``timezone`` argument.
 
-The only other backwards incompatible change was that ``get_next_fire_time()`` takes two arguments
-now: the previous fire time and the current datetime.
+The only other backwards incompatible change was that ``get_next_fire_time()`` takes two
+arguments now: the previous fire time and the current datetime.
 
 
 From v1.x to 2.0
@@ -196,13 +193,12 @@ API changes
 * dump_jobs() is now print_jobs() and prints directly to the given file or
   sys.stdout if none is given
 * The ``repeat`` parameter was removed from
-  :meth:`~apscheduler.scheduler.Scheduler.add_interval_job` and
-  :meth:`~apscheduler.scheduler.Scheduler.interval_schedule` in favor of the
+  ``Scheduler.add_interval_job()`` and ``@Scheduler.interval_schedule`` in favor of the
   universal ``max_runs`` option
-* :meth:`~apscheduler.scheduler.Scheduler.unschedule_func` now raises a
-  KeyError if the given function is not scheduled
-* The semantics of :meth:`~apscheduler.scheduler.Scheduler.shutdown` have
-  changed -- the method no longer accepts a numeric argument, but two booleans
+* ``Scheduler.unschedule_func()`` now raises a :exc:`KeyError` if the given function is
+  not scheduled
+* The semantics of ``Scheduler.shutdown()`` have changed – the method no longer accepts
+  a numeric argument, but two booleans
 
 
 Configuration changes

docs/userguide.rst

@@ -275,7 +275,7 @@ It is possible to control the maximum number of concurrently running jobs for a
 particular task. By default, only one job is allowed to be run for every task.
 This means that if the job is about to be run but there is another job for the same task
 still running, the later job is terminated with the outcome of
-:data:`~JobOutcome.missed_start_deadline`.
+:attr:`~JobOutcome.missed_start_deadline`.
 
 To allow more jobs to be concurrently running for a task, pass the desired maximum
 number as the ``max_running_jobs`` keyword argument to
@@ -284,14 +284,13 @@ number as the ``max_running_jobs`` keyword argument to
 Controlling how much a job can be started late
 ----------------------------------------------
 
-Some tasks are time sensitive, and should not be run at all if it fails to be started on
-time (like, for example, if the scheduler(s) were down while they were supposed to be
+Some tasks are time sensitive, and should not be run at all if they fail to be started
+on time (like, for example, if the scheduler(s) were down while they were supposed to be
 running the scheduled jobs). You can control this time limit with the
-``misfire_grace_time`` option passed to
-:meth:`~Scheduler.add_schedule`. A scheduler that acquires
-the job then checks if the current time is later than the deadline
+``misfire_grace_time`` option passed to :meth:`~Scheduler.add_schedule`. A scheduler
+that acquires the job then checks if the current time is later than the deadline
 (run time + misfire grace time) and if it is, it skips the execution of the job and
-releases it with the outcome of :data:`~JobOutcome.`
+releases it with the outcome of :attr:`~JobOutcome.missed_start_deadline`.
 
 Controlling how jobs are queued from schedules
 ----------------------------------------------

pyproject.toml

@@ -132,6 +132,6 @@ deps = pyright
 commands = pyright --verifytypes apscheduler
 
 [testenv:docs]
-extras = test,doc
+extras = doc
 commands = sphinx-build -n docs build/sphinx
 """

src/apscheduler/__init__.py

@@ -37,6 +37,7 @@
 from ._exceptions import ScheduleLookupError as ScheduleLookupError
 from ._exceptions import SerializationError as SerializationError
 from ._exceptions import TaskLookupError as TaskLookupError
+from ._retry import RetryMixin as RetryMixin
 from ._retry import RetrySettings as RetrySettings
 from ._schedulers.async_ import AsyncScheduler as AsyncScheduler
 from ._schedulers.sync import Scheduler as Scheduler