Raise when unknown signals are connected to CallbackRegistries.

I chose not to emit warnings during a deprecation period as otherwise
the semantics of the `signals` parameter would again have to change at
the end of the deprecation period (from warning to raising), which would
be another backcompatibility break...

Author: anntzer

doc/api/next_api_changes/behavior/21238-AL.rst

@@ -0,0 +1,6 @@
+``CallbackRegistry`` raises on unknown signals
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+When Matplotlib instantiates a `.CallbackRegistry`, it now limits callbacks
+to the signals that the registry knows about.  In practice, this means that
+calling `~.FigureCanvasBase.mpl_connect` with an invalid signal name now raises
+a `ValueError`.

lib/matplotlib/artist.py

@@ -167,7 +167,7 @@ def __init__(self):
         # Normally, artist classes need to be queried for mouseover info if and
         # only if they override get_cursor_data.
         self._mouseover = type(self).get_cursor_data != Artist.get_cursor_data
-        self._callbacks = cbook.CallbackRegistry()
+        self._callbacks = cbook.CallbackRegistry(signals=["pchanged"])
         try:
             self.axes = None
         except AttributeError:

lib/matplotlib/axes/_base.py

@@ -1199,7 +1199,8 @@ def cla(self):
             spine.clear()
 
         self.ignore_existing_data_limits = True
-        self.callbacks = cbook.CallbackRegistry()
+        self.callbacks = cbook.CallbackRegistry(
+            signals=["xlim_changed", "ylim_changed", "zlim_changed"])
 
         if self._sharex is not None:
             self.sharex(self._sharex)

lib/matplotlib/axis.py

@@ -655,7 +655,8 @@ def __init__(self, axes, pickradius=15):
         self.axes = axes
         self.major = Ticker()
         self.minor = Ticker()
-        self.callbacks = cbook.CallbackRegistry()
+        self.callbacks = cbook.CallbackRegistry(
+            signals=["units", "units finalize"])
 
         self._autolabelpos = True
 
@@ -806,7 +807,8 @@ def clear(self):
         self._set_scale('linear')
 
         # Clear the callback registry for this axis, or it may "leak"
-        self.callbacks = cbook.CallbackRegistry()
+        self.callbacks = cbook.CallbackRegistry(
+            signals=["units", "units finalize"])
 
         # whether the grids are on
         self._major_tick_kw['gridOn'] = (

lib/matplotlib/cbook/__init__.py

@@ -175,13 +175,20 @@ class CallbackRegistry:
        The default handler prints the exception (with `traceback.print_exc`) if
        an interactive event loop is running; it re-raises the exception if no
        interactive event loop is running.
+
+    signals : list, optional
+        If not None, *signals* is a list of signals that this registry handles:
+        attempting to `process` or to `connect` to a signal not in the list
+        throws a `ValueError`.  The default, None, does not restrict the
+        handled signals.
     """
 
     # We maintain two mappings:
     #   callbacks: signal -> {cid -> weakref-to-callback}
     #   _func_cid_map: signal -> {weakref-to-callback -> cid}
 
-    def __init__(self, exception_handler=_exception_printer):
+    def __init__(self, exception_handler=_exception_printer, *, signals=None):
+        self._signals = None if signals is None else list(signals)  # Copy it.
         self.exception_handler = exception_handler
         self.callbacks = {}
         self._cid_gen = itertools.count()
@@ -217,6 +224,8 @@ def connect(self, signal, func):
         if signal == "units finalize":
             _api.warn_deprecated(
                 "3.5", name=signal, obj_type="signal", alternative="units")
+        if self._signals is not None:
+            _api.check_in_list(self._signals, signal=signal)
         self._func_cid_map.setdefault(signal, {})
         proxy = _weak_or_strong_ref(func, self._remove_proxy)
         if proxy in self._func_cid_map[signal]:
@@ -280,6 +289,8 @@ def process(self, s, *args, **kwargs):
         All of the functions registered to receive callbacks on *s* will be
         called with ``*args`` and ``**kwargs``.
         """
+        if self._signals is not None:
+            _api.check_in_list(self._signals, signal=s)
         for cid, ref in list(self.callbacks.get(s, {}).items()):
             func = ref()
             if func is not None:

lib/matplotlib/cm.py

@@ -359,7 +359,7 @@ def __init__(self, norm=None, cmap=None):
         self.set_cmap(cmap)  # The Colormap instance of this ScalarMappable.
         #: The last colorbar associated with this ScalarMappable. May be None.
         self.colorbar = None
-        self.callbacks = cbook.CallbackRegistry()
+        self.callbacks = cbook.CallbackRegistry(signals=["changed"])
 
     callbacksSM = _api.deprecated("3.5", alternative="callbacks")(
         property(lambda self: self.callbacks))

lib/matplotlib/colors.py

@@ -1132,7 +1132,7 @@ def __init__(self, vmin=None, vmax=None, clip=False):
         self._vmax = _sanitize_extrema(vmax)
         self._clip = clip
         self._scale = None
-        self.callbacks = cbook.CallbackRegistry()
+        self.callbacks = cbook.CallbackRegistry(signals=["changed"])
 
     @property
     def vmin(self):

lib/matplotlib/container.py

@@ -18,7 +18,7 @@ def __new__(cls, *args, **kwargs):
         return tuple.__new__(cls, args[0])
 
     def __init__(self, kl, label=None):
-        self._callbacks = cbook.CallbackRegistry()
+        self._callbacks = cbook.CallbackRegistry(signals=["pchanged"])
         self._remove_method = None
         self.set_label(label)
 

lib/matplotlib/figure.py

@@ -2249,11 +2249,12 @@ def __init__(self,
             else:
                 _api.check_in_list(['constrained', 'tight'], layout=layout)
 
-        self.callbacks = cbook.CallbackRegistry()
+        self.callbacks = cbook.CallbackRegistry(signals=["dpi_changed"])
         # Callbacks traditionally associated with the canvas (and exposed with
         # a proxy property), but that actually need to be on the figure for
         # pickling.
-        self._canvas_callbacks = cbook.CallbackRegistry()
+        self._canvas_callbacks = cbook.CallbackRegistry(
+            signals=FigureCanvasBase.events)
         self._button_pick_id = self._canvas_callbacks.connect(
             'button_press_event', lambda event: self.canvas.pick(event))
         self._scroll_pick_id = self._canvas_callbacks.connect(

lib/matplotlib/tests/test_cbook.py

@@ -363,6 +363,19 @@ def test_callbackregistry_custom_exception_handler(monkeypatch, cb, excp):
         cb.process('foo')
 
 
+def test_callbackregistry_signals():
+    cr = cbook.CallbackRegistry(signals=["foo"])
+    results = []
+    def cb(x): results.append(x)
+    cr.connect("foo", cb)
+    with pytest.raises(ValueError):
+        cr.connect("bar", cb)
+    cr.process("foo", 1)
+    with pytest.raises(ValueError):
+        cr.process("bar", 1)
+    assert results == [1]
+
+
 def test_callbackregistry_blocking():
     # Needs an exception handler for interactive testing environments
     # that would only print this out instead of raising the exception