simplify into single function with overload and api rename

ianhi · ianhi · commit da7a5cc573af · 2025-12-13T14:52:14.000-05:00
diff --git a/doc/api/next_api_changes/deprecations/30844-IHI.rst b/doc/api/next_api_changes/deprecations/30844-IHI.rst
@@ -0,0 +1,9 @@
+``CallbackRegistry.disconnect`` *cid* parameter renamed to *cid_or_func*
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The *cid* parameter of `.CallbackRegistry.disconnect` has been renamed to
+*cid_or_func*. The method now also accepts a callable, which will disconnect
+that callback from all signals or from a specific signal if the *signal*
+keyword argument is provided.
+
+``CallbackRegistry.disconnect_func`` has been removed; use
+``disconnect(func, signal=...)`` instead.
diff --git a/lib/matplotlib/cbook.py b/lib/matplotlib/cbook.py
@@ -229,7 +229,7 @@ class CallbackRegistry:
         >>> callbacks.process('drink', 123)
         drink 123
 
-        >>> callbacks.disconnect_func('drink', ondrink)  # disconnect by func
+        >>> callbacks.disconnect(ondrink, signal='drink')  # disconnect by func
         >>> callbacks.process('drink', 123)      # nothing will be called
 
     In practice, one should always disconnect all callbacks when they are
@@ -334,27 +334,45 @@ def _remove_proxy(self, signal, proxy, *, _is_finalizing=sys.is_finalizing):
         if len(self.callbacks[signal]) == 0:  # Clean up empty dicts
             del self.callbacks[signal]
 
-    def disconnect(self, cid):
+    @_api.rename_parameter("3.11", "cid", "cid_or_func")
+    def disconnect(self, cid_or_func, *, signal=None):
         """
-        Disconnect the callback registered with callback id *cid*.
-
-        No error is raised if such a callback does not exist.
-        """
-        for signal, proxy in self._func_cid_map:
-            if self._func_cid_map[signal, proxy] == cid:
-                break
-        else:  # Not found
-            return
-        self._remove_proxy(signal, proxy)
-
-    def disconnect_func(self, signal, func):
-        """
-        Disconnect the callback for *func* registered to *signal*.
+        Disconnect a callback.
 
+        Parameters
+        ----------
+        cid_or_func : int or callable
+            If an int, disconnect the callback with that connection id.
+            If a callable, disconnect that function from signals.
+        signal : optional
+            Only used when *cid_or_func* is a callable. If given, disconnect
+            the function only from that specific signal. If not given,
+            disconnect from all signals the function is connected to.
+
+        Notes
+        -----
         No error is raised if such a callback does not exist.
         """
-        proxy = _weak_or_strong_ref(func, None)
-        self._remove_proxy(signal, proxy)
+        if isinstance(cid_or_func, int):
+            if signal is not None:
+                raise ValueError(
+                    "signal cannot be specified when disconnecting by cid")
+            for sig, proxy in self._func_cid_map:
+                if self._func_cid_map[sig, proxy] == cid_or_func:
+                    break
+            else:  # Not found
+                return
+            self._remove_proxy(sig, proxy)
+        elif signal is not None:
+            # Disconnect from a specific signal
+            proxy = _weak_or_strong_ref(cid_or_func, None)
+            self._remove_proxy(signal, proxy)
+        else:
+            # Disconnect from all signals
+            proxy = _weak_or_strong_ref(cid_or_func, None)
+            for sig, prx in list(self._func_cid_map):
+                if prx == proxy:
+                    self._remove_proxy(sig, proxy)
 
     def process(self, s, *args, **kwargs):
         """
diff --git a/lib/matplotlib/cbook.pyi b/lib/matplotlib/cbook.pyi
@@ -33,8 +33,10 @@ class CallbackRegistry:
         signals: Iterable[Any] | None = ...,
     ) -> None: ...
     def connect(self, signal: Any, func: Callable) -> int: ...
-    def disconnect(self, cid: int) -> None: ...
-    def disconnect_func(self, signal: Any, func: Callable) -> None: ...
+    @overload
+    def disconnect(self, cid_or_func: int) -> None: ...
+    @overload
+    def disconnect(self, cid_or_func: Callable, *, signal: Any | None = ...) -> None: ...
     def process(self, s: Any, *args, **kwargs) -> None: ...
     def blocked(
         self, *, signal: Any | None = ...
diff --git a/lib/matplotlib/tests/test_cbook.py b/lib/matplotlib/tests/test_cbook.py
@@ -306,7 +306,7 @@ def test_callback_disconnect_func(self, pickle, cls):
         self.is_not_empty()
 
         # disconnect by function reference
-        self.callbacks.disconnect_func(self.signal, mini_me.dummy)
+        self.callbacks.disconnect(mini_me.dummy, signal=self.signal)
 
         # check we now have no callbacks registered
         self.is_empty()
@@ -325,22 +325,22 @@ def test_callback_disconnect_func_wrong(self, pickle, cls):
         self.is_not_empty()
 
         # try to disconnect with wrong signal - should do nothing
-        self.callbacks.disconnect_func('wrong_signal', mini_me.dummy)
+        self.callbacks.disconnect(mini_me.dummy, signal='wrong_signal')
 
         # check we still have callbacks registered
         self.is_not_empty()
 
         # try to disconnect with wrong function - should do nothing
         mini_me2 = cls()
-        self.callbacks.disconnect_func(self.signal, mini_me2.dummy)
+        self.callbacks.disconnect(mini_me2.dummy, signal=self.signal)
 
         # check we still have callbacks registered
         self.is_not_empty()
 
     def test_callback_disconnect_func_redefined(self):
-        # Test that redefining a function name doesn't affect disconnect_func.
+        # Test that redefining a function name doesn't affect disconnect.
         # When you redefine a function, it creates a new function object,
-        # so disconnect_func should not disconnect the original.
+        # so disconnect should not disconnect the original.
         self.is_empty()
 
         def func():
@@ -354,11 +354,65 @@ def func():
             pass
 
         # Try to disconnect with the redefined function
-        self.callbacks.disconnect_func(self.signal, func)
+        self.callbacks.disconnect(func, signal=self.signal)
 
         # Original callback should still be registered
         self.is_not_empty()
 
+    @pytest.mark.parametrize('pickle', [True, False])
+    @pytest.mark.parametrize('cls', [Hashable, Unhashable])
+    def test_callback_disconnect_func_all_signals(self, pickle, cls):
+        # Test disconnecting a callback from all signals at once
+        self.is_empty()
+
+        mini_me = cls()
+
+        # Connect to multiple signals
+        self.callbacks.connect('signal1', mini_me.dummy)
+        self.callbacks.connect('signal2', mini_me.dummy)
+        assert len(list(self.callbacks._func_cid_map)) == 2
+
+        # Disconnect from all signals at once (no signal specified)
+        self.callbacks.disconnect(mini_me.dummy)
+
+        # All callbacks should be removed
+        self.is_empty()
+
+    def test_disconnect_cid_with_signal_raises(self):
+        # Passing signal with a cid should raise an error
+        self.is_empty()
+        cid = self.callbacks.connect(self.signal, lambda: None)
+        with pytest.raises(ValueError, match="signal cannot be specified"):
+            self.callbacks.disconnect(cid, signal=self.signal)
+
+    @pytest.mark.parametrize('pickle', [True, False])
+    @pytest.mark.parametrize('cls', [Hashable, Unhashable])
+    def test_callback_disconnect_func_selective(self, pickle, cls):
+        # Test selectively disconnecting a callback from one signal
+        # while keeping it connected to another
+        self.is_empty()
+
+        mini_me = cls()
+
+        # Connect same function to multiple signals
+        self.callbacks.connect('signal1', mini_me.dummy)
+        self.callbacks.connect('signal2', mini_me.dummy)
+        assert len(list(self.callbacks._func_cid_map)) == 2
+
+        # Disconnect from only signal1
+        self.callbacks.disconnect(mini_me.dummy, signal='signal1')
+
+        # Should still have one callback registered (on signal2)
+        assert len(list(self.callbacks._func_cid_map)) == 1
+        assert 'signal2' in self.callbacks.callbacks
+        assert 'signal1' not in self.callbacks.callbacks
+
+        # Disconnect from signal2
+        self.callbacks.disconnect(mini_me.dummy, signal='signal2')
+
+        # Now all should be removed
+        self.is_empty()
+
     @pytest.mark.parametrize('pickle', [True, False])
     @pytest.mark.parametrize('cls', [Hashable, Unhashable])
     def test_registration_on_non_empty_registry(self, pickle, cls):
