Merge branch 'matplotlib:main' into fix-subplots-typing

n-takumasa · web-flow · commit a62d311bb683 · 2023-10-06T08:35:12.000+09:00
diff --git a/doc/api/next_api_changes/deprecations/26894-AL.rst b/doc/api/next_api_changes/deprecations/26894-AL.rst
@@ -0,0 +1,6 @@
+*interval* parameter of ``TimerBase.start``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Setting the timer *interval* while starting it is deprecated.  The interval can
+be specified instead in the timer constructor, or by setting the
+``timer.interval`` attribute.
diff --git a/doc/users/next_whats_new/widget_button_clear.rst b/doc/users/next_whats_new/widget_button_clear.rst
@@ -0,0 +1,6 @@
+Check and Radio Button widgets support clearing
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The `.CheckButtons` and `.RadioButtons` widgets now support clearing their
+state by calling their ``.clear`` method. Note that it is not possible to have
+no selected radio buttons, so the selected option at construction time is selected.
diff --git a/lib/matplotlib/axis.py b/lib/matplotlib/axis.py
@@ -1961,8 +1961,9 @@ def set_ticklabels(self, labels, *, minor=False, fontdict=None, **kwargs):
         ----------
         labels : sequence of str or of `.Text`\s
             Texts for labeling each tick location in the sequence set by
-            `.Axis.set_ticks`; the number of labels must match the number of
-            locations.
+            `.Axis.set_ticks`; the number of labels must match the number of locations.
+            The labels are used as is, via a `.FixedFormatter` (without further
+            formatting).
 
         minor : bool
             If True, set minor ticks instead of major ticks.
@@ -2093,26 +2094,25 @@ def set_ticks(self, ticks, labels=None, *, minor=False, **kwargs):
         Parameters
         ----------
         ticks : 1D array-like
-            Array of tick locations.  The axis `.Locator` is replaced by a
-            `~.ticker.FixedLocator`.
+            Array of tick locations (either floats or in axis units). The axis
+            `.Locator` is replaced by a `~.ticker.FixedLocator`.
 
-            The values may be either floats or in axis units.
-
-            Pass an empty list to remove all ticks::
-
-                set_ticks([])
+            Pass an empty list (``set_ticks([])``) to remove all ticks.
 
             Some tick formatters will not label arbitrary tick positions;
             e.g. log formatters only label decade ticks by default. In
             such a case you can set a formatter explicitly on the axis
             using `.Axis.set_major_formatter` or provide formatted
             *labels* yourself.
+
         labels : list of str, optional
-            Tick labels for each location in *ticks*. *labels* must be of the same
-            length as *ticks*. If not set, the labels are generate using the axis
-            tick `.Formatter`.
+            Tick labels for each location in *ticks*; must have the same length as
+            *ticks*. If set, the labels are used as is, via a `.FixedFormatter`.
+            If not set, the labels are generated using the axis tick `.Formatter`.
+
         minor : bool, default: False
             If ``False``, set the major ticks; if ``True``, the minor ticks.
+
         **kwargs
             `.Text` properties for the labels. Using these is only allowed if
             you pass *labels*. In other cases, please use `~.Axes.tick_params`.
diff --git a/lib/matplotlib/backend_bases.py b/lib/matplotlib/backend_bases.py
@@ -1117,6 +1117,7 @@ def __del__(self):
         """Need to stop timer and possibly disconnect timer."""
         self._timer_stop()
 
+    @_api.delete_parameter("3.9", "interval", alternative="timer.interval")
     def start(self, interval=None):
         """
         Start the timer object.
diff --git a/lib/matplotlib/tests/test_widgets.py b/lib/matplotlib/tests/test_widgets.py
@@ -1004,10 +1004,23 @@ def test_lasso_selector_set_props(ax):
 
 
 def test_CheckButtons(ax):
-    check = widgets.CheckButtons(ax, ('a', 'b', 'c'), (True, False, True))
+    labels = ('a', 'b', 'c')
+    check = widgets.CheckButtons(ax, labels, (True, False, True))
     assert check.get_status() == [True, False, True]
     check.set_active(0)
     assert check.get_status() == [False, False, True]
+    assert check.get_checked_labels() == ['c']
+    check.clear()
+    assert check.get_status() == [False, False, False]
+    assert check.get_checked_labels() == []
+
+    for invalid_index in [-1, len(labels), len(labels)+5]:
+        with pytest.raises(ValueError):
+            check.set_active(index=invalid_index)
+
+    for invalid_value in ['invalid', -1]:
+        with pytest.raises(TypeError):
+            check.set_active(1, state=invalid_value)
 
     cid = check.on_clicked(lambda: None)
     check.disconnect(cid)
@@ -1045,6 +1058,16 @@ def test_TextBox(ax, toolbar):
     assert text_change_event.call_count == 3
 
 
+def test_RadioButtons(ax):
+    radio = widgets.RadioButtons(ax, ('Radio 1', 'Radio 2', 'Radio 3'))
+    radio.set_active(1)
+    assert radio.value_selected == 'Radio 2'
+    assert radio.index_selected == 1
+    radio.clear()
+    assert radio.value_selected == 'Radio 1'
+    assert radio.index_selected == 0
+
+
 @image_comparison(['check_radio_buttons.png'], style='mpl20', remove_text=True)
 def test_check_radio_buttons_image():
     ax = get_ax()
diff --git a/lib/matplotlib/widgets.py b/lib/matplotlib/widgets.py
@@ -1176,9 +1176,9 @@ def set_check_props(self, props):
         # If new colours are supplied, then we must re-apply the status.
         self._init_status(actives)
 
-    def set_active(self, index):
+    def set_active(self, index, state=None):
         """
-        Toggle (activate or deactivate) a check button by index.
+        Modify the state of a check button by index.
 
         Callbacks will be triggered if :attr:`eventson` is True.
 
@@ -1187,22 +1187,27 @@ def set_active(self, index):
         index : int
             Index of the check button to toggle.
 
+        state : bool, optional
+            If a boolean value, set the state explicitly. If no value is
+            provided, the state is toggled.
+
         Raises
         ------
         ValueError
             If *index* is invalid.
+        TypeError
+            If *state* is not boolean.
         """
         if index not in range(len(self.labels)):
             raise ValueError(f'Invalid CheckButton index: {index}')
+        _api.check_isinstance((bool, None), state=state)
 
         invisible = colors.to_rgba('none')
 
         facecolors = self._checks.get_facecolor()
-        facecolors[index] = (
-            self._active_check_colors[index]
-            if colors.same_color(facecolors[index], invisible)
-            else invisible
-        )
+        if state is None:
+            state = colors.same_color(facecolors[index], invisible)
+        facecolors[index] = self._active_check_colors[index] if state else invisible
         self._checks.set_facecolor(facecolors)
 
         if self.drawon:
@@ -1233,18 +1238,55 @@ def _init_status(self, actives):
             [ec if active else "none"
              for ec, active in zip(self._active_check_colors, actives)])
 
+    def clear(self):
+        """Uncheck all checkboxes."""
+
+        self._checks.set_facecolor(['none'] * len(self._active_check_colors))
+
+        if hasattr(self, '_lines'):
+            for l1, l2 in self._lines:
+                l1.set_visible(False)
+                l2.set_visible(False)
+
+        if self.drawon:
+            self.canvas.draw()
+
+        if self.eventson:
+            # Call with no label, as all checkboxes are being cleared.
+            self._observers.process('clicked', None)
+
     def get_status(self):
         """
         Return a list of the status (True/False) of all of the check buttons.
         """
         return [not colors.same_color(color, colors.to_rgba("none"))
                 for color in self._checks.get_facecolors()]
 
+    def get_checked_labels(self):
+        """Return a list of labels currently checked by user."""
+
+        return [l.get_text() for l, box_checked in
+                zip(self.labels, self.get_status())
+                if box_checked]
+
     def on_clicked(self, func):
         """
         Connect the callback function *func* to button click events.
 
-        Returns a connection id, which can be used to disconnect the callback.
+        Parameters
+        ----------
+        func : callable
+            When the button is clicked, call *func* with button label.
+            When all buttons are cleared, call *func* with None.
+            The callback func must have the signature::
+
+                def func(label: str | None) -> Any
+
+            Return values may exist, but are ignored.
+
+        Returns
+        -------
+        A connection id, which can be used to disconnect the callback.
         """
         return self._observers.connect('clicked', lambda text: func(text))
 
@@ -1533,6 +1575,8 @@ class RadioButtons(AxesWidget):
         The buttons.
     value_selected : str
         The label text of the currently selected button.
+    index_selected : int
+        The index of the selected button.
     """
 
     def __init__(self, ax, labels, active=0, activecolor=None, *,
@@ -1590,7 +1634,9 @@ def __init__(self, ax, labels, active=0, activecolor=None, *,
             activecolor = 'blue'  # Default.
 
         self._activecolor = activecolor
+        self._initial_active = active
         self.value_selected = labels[active]
+        self.index_selected = active
 
         ax.set_xticks([])
         ax.set_yticks([])
@@ -1716,10 +1762,21 @@ def set_active(self, index):
         Select button with number *index*.
 
         Callbacks will be triggered if :attr:`eventson` is True.
+
+        Parameters
+        ----------
+        index : int
+            The index of the button to activate.
+
+        Raises
+        ------
+        ValueError
+            If the index is invalid.
         """
         if index not in range(len(self.labels)):
             raise ValueError(f'Invalid RadioButton index: {index}')
         self.value_selected = self.labels[index].get_text()
+        self.index_selected = index
         button_facecolors = self._buttons.get_facecolor()
         button_facecolors[:] = colors.to_rgba("none")
         button_facecolors[index] = colors.to_rgba(self._active_colors[index])
@@ -1737,11 +1794,28 @@ def set_active(self, index):
         if self.eventson:
             self._observers.process('clicked', self.labels[index].get_text())
 
+    def clear(self):
+        """Reset the active button to the initially active one."""
+        self.set_active(self._initial_active)
+
     def on_clicked(self, func):
         """
         Connect the callback function *func* to button click events.
 
-        Returns a connection id, which can be used to disconnect the callback.
+        Parameters
+        ----------
+        func : callable
+            When the button is clicked, call *func* with button label.
+            When all buttons are cleared, call *func* with None.
+            The callback func must have the signature::
+
+                def func(label: str | None) -> Any
+
+            Return values may exist, but are ignored.
+
+        Returns
+        -------
+        A connection id, which can be used to disconnect the callback.
         """
         return self._observers.connect('clicked', func)
 
diff --git a/lib/matplotlib/widgets.pyi b/lib/matplotlib/widgets.pyi
@@ -160,9 +160,11 @@ class CheckButtons(AxesWidget):
     def set_label_props(self, props: dict[str, Any]) -> None: ...
     def set_frame_props(self, props: dict[str, Any]) -> None: ...
     def set_check_props(self, props: dict[str, Any]) -> None: ...
-    def set_active(self, index: int) -> None: ...
+    def set_active(self, index: int, state: bool | None = ...) -> None: ...  # type: ignore[override]
+    def clear(self) -> None: ...
     def get_status(self) -> list[bool]: ...
-    def on_clicked(self, func: Callable[[str], Any]) -> int: ...
+    def get_checked_labels(self) -> list[str]: ...
+    def on_clicked(self, func: Callable[[str | None], Any]) -> int: ...
     def disconnect(self, cid: int) -> None: ...
 
 class TextBox(AxesWidget):
@@ -211,7 +213,8 @@ class RadioButtons(AxesWidget):
     def set_label_props(self, props: dict[str, Any]) -> None: ...
     def set_radio_props(self, props: dict[str, Any]) -> None: ...
     def set_active(self, index: int) -> None: ...
-    def on_clicked(self, func: Callable[[str], Any]) -> int: ...
+    def clear(self) -> None: ...
+    def on_clicked(self, func: Callable[[str | None], Any]) -> int: ...
     def disconnect(self, cid: int) -> None: ...
 
 class SubplotTool(Widget):
