I don't know how to fix the other rstcheck CI errors...

I have opened #30810 for the rstcheck errors.

a horizontal layout must be created via labels=[['button1', 'button2', 'button3']] which is not quite intuitive

That's also how .subplot_mosaic works - it's slightly annoying but also not really a big deal

a horizontal layout must be created via labels=[['button1', 'button2', 'button3']] which is not quite intuitive

That's also how .subplot_mosaic works - it's slightly annoying but also not really a big deal

I agree. I added a commit that explains this explicitly. I was also wondering, would you be interested in a similar change to CheckButtons?

The difference with subplot_mosaic is that in general you want explicit placing in 2D and "N elements in a row" is just a special case. I'd claim that one never actually wants to define "button_i is in the third row of the second column." It's rather that you have a logical 1D list of elements and want to arrange them, most commonly all vertical, or all horizontal. The better analogy would be legend(), not subplot_mosaic() (though one could make a better API than controlling the behavior via ncols).

One option would be a layout parameter (naming and details t.b.d.) with values

• "horizontal"
• "vertical"
• (rows, columns) as a grid, maybe extending this with a fill-order, e.g. (2, 5, "row-first").
  This would also be a reasonable extension for legend() and could replace ncols there in the long term.

I was also wondering, would you be interested in a similar change to CheckButtons?

Yes, CheckButtons should be handled analogously, but first let’s clarify the API.

One option would be a layout parameter (naming and details t.b.d.) with values

• "horizontal"
• "vertical"
• (rows, columns) as a grid, maybe extending this with a fill-order, e.g. (2, 5, "row-first").

This would also be a reasonable extension for legend() and could replace ncols there in the long term.

This indeed feels like a pretty good API. I won't mind implementing it, but you should note that at the moment it is possible to use:

buttons=[["A", "B"], ["C"]]

Which produces:

So are we sure we don't want to allow this behavior?

you should note that at the moment it is possible to use:

buttons=[["A", "B"], ["C"]]

You can achieve the same with labels=["A", "B", "C"], layout=(2, 2) - maybe ... layout=(2, 2, "row-first") depending on how we fill by default.

I concede that more complex arrangements like

A B
C
D E

are not possible. - We can later expand that API by either allowing None as an empty placeholder in the list or by then introducing 2D labels for explicit placement. But I would leave such extensions to when actual user requests arise.

OK that's pretty convincing. Thinking about this again, at the moment I avoided taking care of inputs like: labels=["A", "B", "C"], layout=(2, 2) because TBH it doesn't look that nice and as you said it can be implemented in the future with None, while still demanding the amount of labels will fit the multiplication of the layout tuple.

As for layout=(2, 2, "row-first"), it can be achieved via reordering the input labels, so I haven't implemented support for this too.

Now this feature is thoroughly tested, both the Python and Rst examples.

@timhoffm since I used the same algorithm to distribute the buttons and texts for horizontal layouts too, there are tests failing now due to slight differences in the positions of the elements. Would you accept these differences?

check_radio_buttons[png]

My distribution:

Current distribution:

test_radio_buttons[png]

My distribution:

Current distribution:

Overall, I find this a bit too invasive to immediately roll out; in particular because (1) it temporarily adds artists and triggers a draw and (2) it changes the positions of the buttons.

Let's do the following: factor the position calculation out into a separate function, and introduce layout=None, which reproduces the existing behavior

        if layout is None:
            button_xs, button_ys, label_xs, label_ys = _legacy_radio_layout(labels, ...)
        else:
            button_xs, button_ys, label_xs, label_ys = _radio_layout(labels, ...)

        [...]

        self.labels = [
            ax.text(x, y, label, transform=ax.transAxes,
                    horizontalalignment="left", verticalalignment="center",
                    **props)
            for x, y, label, props in zip(label_xs, label_ys, labels, label_props)]
        [...]
        self._buttons = ax.scatter(button_xs, button_ys, **radio_props)

By defining layout=None we can keep the existing behavior by default for now and make the new layout opt-in.

Indeed outsourcing this layout algorithm would be useful also for CheckButtons. This should be good now (TBH, here on NixOS I experience an RMS 6.101 failure for test_check_radio_buttons_image[png] even on branch main, but that's out of scope for this PR).

Maybe before accepting this change, I should perform this change to CheckButtons?

As you wish. The inclusion of CheckButtons is small enough so that it can be done here, but it can also be done in a followup PR.

Python 3.11 on ubuntu-22.04 (Minimum Versions) failures are unrelated...