Enhanced typing of subscribe()

This PR adds type var `T_Event` and uses it to type the `subscribe()` interfaces.

Fixes an issue where subscribing a handler would raise a type error if the handler is typed to receive a subclass of `Event`.

Allows type checkers to verify that the handler passed to `subscribe()` can support the event types it is assigned to handle.

Closes #846

src/apscheduler/_events.py

@@ -3,7 +3,7 @@
 from datetime import datetime, timezone
 from functools import partial
 from traceback import format_tb
-from typing import Any
+from typing import Any, TypeVar
 from uuid import UUID
 
 import attrs
@@ -14,6 +14,8 @@
 from ._structures import Job, JobResult
 from ._utils import qualified_name
 
+T_Event = TypeVar("T_Event", bound="Event")
+
 
 @attrs.define(kw_only=True, frozen=True)
 class Event:

src/apscheduler/_schedulers/async_.py

@@ -38,6 +38,7 @@
     SchedulerStarted,
     SchedulerStopped,
     ScheduleUpdated,
+    T_Event,
 )
 from .._exceptions import (
     CallableLookupError,
@@ -216,8 +217,8 @@ async def cleanup(self) -> None:
 
     def subscribe(
         self,
-        callback: Callable[[Event], Any],
-        event_types: type[Event] | Iterable[type[Event]] | None = None,
+        callback: Callable[[T_Event], Any],
+        event_types: type[T_Event] | Iterable[type[T_Event]] | None = None,
         *,
         one_shot: bool = False,
         is_async: bool = True,

src/apscheduler/_schedulers/sync.py

@@ -15,7 +15,8 @@
 
 from anyio.from_thread import BlockingPortal, start_blocking_portal
 
-from .. import Event, current_scheduler
+from .. import current_scheduler
+from .._events import T_Event
 from .._enums import CoalescePolicy, ConflictPolicy, RunState, SchedulerRole
 from .._structures import Job, JobResult, Schedule, Task
 from .._utils import UnsetValue, unset
@@ -157,8 +158,8 @@ def cleanup(self) -> None:
 
     def subscribe(
         self,
-        callback: Callable[[Event], Any],
-        event_types: Iterable[type[Event]] | None = None,
+        callback: Callable[[T_Event], Any],
+        event_types: Iterable[type[T_Event]] | None = None,
         *,
         one_shot: bool = False,
     ) -> Subscription:

src/apscheduler/abc.py

@@ -15,7 +15,7 @@
 
 if TYPE_CHECKING:
     from ._enums import ConflictPolicy
-    from ._events import Event
+    from ._events import Event, T_Event
     from ._structures import Job, JobResult, Schedule, Task
 
 
@@ -135,8 +135,8 @@ async def publish_local(self, event: Event) -> None:
     @abstractmethod
     def subscribe(
         self,
-        callback: Callable[[Event], Any],
-        event_types: Iterable[type[Event]] | None = None,
+        callback: Callable[[T_Event], Any],
+        event_types: Iterable[type[T_Event]] | None = None,
         *,
         is_async: bool = True,
         one_shot: bool = False,

src/apscheduler/eventbrokers/base.py

@@ -11,7 +11,7 @@
 from anyio.abc import TaskGroup
 
 from .. import _events
-from .._events import Event
+from .._events import Event, T_Event
 from .._exceptions import DeserializationError
 from .._retry import RetryMixin
 from ..abc import EventBroker, Serializer, Subscription
@@ -47,8 +47,8 @@ async def start(self, exit_stack: AsyncExitStack, logger: Logger) -> None:
 
     def subscribe(
         self,
-        callback: Callable[[Event], Any],
-        event_types: Iterable[type[Event]] | None = None,
+        callback: Callable[[T_Event], Any],
+        event_types: Iterable[type[T_Event]] | None = None,
         *,
         is_async: bool = True,
         one_shot: bool = False,