Merge pull request matplotlib#30590 from timhoffm/eventsource

MNT: Define Protocol for Animation.event_source

Author: QuLogic

ci/mypy-stubtest-allowlist.txt

@@ -49,3 +49,6 @@ matplotlib\.figure\.FigureBase\.get_figure
 
 # getitem method only exists for 3.10 deprecation backcompatability
 matplotlib\.inset\.InsetIndicator\.__getitem__
+
+# only defined in stubs; not present at runtime
+matplotlib\.animation\.EventSourceProtocol

lib/matplotlib/animation.py

@@ -861,7 +861,7 @@ class Animation:
     fig : `~matplotlib.figure.Figure`
         The figure object used to get needed events, such as draw or resize.
 
-    event_source : object, optional
+    event_source : object
         A class that can run a callback when desired events
         are generated, as well as be stopped and started.
 
@@ -877,7 +877,7 @@ class Animation:
     FuncAnimation,  ArtistAnimation
     """
 
-    def __init__(self, fig, event_source=None, blit=False):
+    def __init__(self, fig, event_source, blit=False):
         self._draw_was_started = False
 
         self._fig = fig

lib/matplotlib/animation.pyi

@@ -6,7 +6,7 @@ from matplotlib.artist import Artist
 from matplotlib.backend_bases import TimerBase
 from matplotlib.figure import Figure
 
-from typing import Any
+from typing import Any, Protocol
 
 subprocess_creation_flags: int
 
@@ -152,11 +152,17 @@ class HTMLWriter(FileMovieWriter):
     def grab_frame(self, **savefig_kwargs): ...
     def finish(self) -> None: ...
 
+class EventSourceProtocol(Protocol):
+    def add_callback(self, func: Callable): ...
+    def remove_callback(self, func: Callable): ...
+    def start(self): ...
+    def stop(self): ...
+
 class Animation:
     frame_seq: Iterable[Artist]
-    event_source: Any
+    event_source: EventSourceProtocol | None  # TODO: We should remove None
     def __init__(
-        self, fig: Figure, event_source: Any | None = ..., blit: bool = ...
+        self, fig: Figure, event_source: EventSourceProtocol, blit: bool = ...
     ) -> None: ...
     def __del__(self) -> None: ...
     def save(