I have a question about **kwargs. Am I correct in thinking that we should be using that inadd_subplot andadd_subfigure, to pass tosub_prep? I got a bit confused and decided to leave things explicit, but this seems like it should be done differently.

I think what you have done makes sense._sub_prep does the checking that there are no common keys insubthing_kw andper_subthing_kw, so it needs to have those dictionaries separate. Or have I misunderstood your question?

@rcomer Thank you for answering!
Maybe I misunderstood the way kwargs processing works. Fom what I gather, we're not using the kwargs that we pass tosubplot_mosaic andsubfigure_mosaic directly. Instead, we're passing them further for_sub_prep to use. So we should be doing something like:

defsubfigure_mosaic(self,mosaic,**kwargs):ret=self._sub_prep(mosaic,self.add_subfigure,kwargs)

instead of what is currently happening. But the definition of_sub_prep should remain the same (explicit key/value definitions) because we're using the kwargs in it.
I had difficulties in implementing it that way though, so I thought I'd get feedback before changing anything.

The reason we do not use**kwargs but instead havesubplot_kw andgridspec_kw is that both of those things have "claim" to the keywords, however we can not reliably separate which keys / values should go to which. In part because one of the keywords that can go toadd_subplot asaxes_class which lets the user switch out the Axes class that will be used and those (sub) classes can have arbitrary keywords (😱) thus there may be a collision withgridspec_kw. Wecould have picked priority in favor ofgridspec_kw, but we opted for being explicit.

Currentlyadd_subfigure does not have that level of flexibility. However I think we should rhyme with the subplot API as much as possible, preserve the ability to add the flexibility in the future, and remain explicit about where internally the keywords are being routed.

It looks like the mosaic tests all passed so that is a good sign!

Code is looking good, now it needs docs, examples and whats new :)

@turnipseason What are the odds of you having time to get this done in the next two weeks? We are getting ready for the 3.8 release and it would be great to get this in for that!

@tacaswell I've been a bit busy the past week but now I think I will have the time to do this!

@tacaswell Hi! I've been trying to write small examples and discovered some problems.

1. The test for "nested" layouts (test_nested) passes, but, for example, if we compare the result to that ofsubplot_mosaic, we can see that it's wrong. It seems like this only happens when having inner lists within other lists, like so:

inner= [ ["inner A"], ["inner B"], ]outer_nested_mosaic= [["main",inner], ["bottom","bottom"],]axda=plt.figure(layout="constrained").subfigure_mosaic(outer_nested_mosaic)

This (with some keywords for clarity + identify_axes) gives us:

Whereassubplot_mosaic with the same parameters looks like:

Is this expected? Should I try to fix this behavior or just write into the docs that it shouldn't be used like that?

2. The second thing is that there are two more tests forsubplot_mosaic that test height and width ratios in nested list situations, using the.get_gridspec(). The first problem is as described above. The second is that for SubFigures that requires calling.gca() but that always results in a (1,1) GridSpec.
   Thetest_nested passes, so just making it an image comparison wouldn't make sense. Is there a different way of doing this?

3. With regards to the examples themselves -- I'm leaning more towards writing a separate file that mimicsthis with elements fromthis, as you said. Should I put it inexamples orusers_explain?

1. Should I try to fix this behavior or just write into the docs that it shouldn't be used like that?

Please try to fix thisor make it error in this case

2. there should be a way to do this without calling.gca()
3. that seems reasonable

writing output... [  4%] api/_as_gen/matplotlib.animation.AbstractMovieWriter .. api/_as_gen/matplotlib.artist.Artist.set_visible/home/circleci/project/lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.subfigure_mosaic:6: WARNING: unknown document: '/gallery/subplots_axes_and_figures/subfig_mosaic'writing output... [  8%] api/_as_gen/matplotlib.artist.Artist.set_zorder .. api/_as_gen/matplotlib.axes.Axes.get_axisbelowwriting output... [ 12%] api/_as_gen/matplotlib.axes.Axes.get_box_aspect .. api/_as_gen/matplotlib.axes.Axes.pcolorfastwriting output... [ 16%] api/_as_gen/matplotlib.axes.Axes.pcolormesh .. api/_as_gen/matplotlib.axes.Axes.vlines/home/circleci/project/lib/matplotlib/figure.py:docstring of matplotlib.figure.FigureBase.subfigure_mosaic:6: WARNING: unknown document: '/gallery/subplots_axes_and_figures/subfig_mosaic'/home/circleci/project/lib/matplotlib/figure.py:docstring of matplotlib.figure.FigureBase.subfigure_mosaic:6: WARNING: unknown document: '/gallery/subplots_axes_and_figures/subfig_mosaic'/home/circleci/project/lib/matplotlib/figure.py:docstring of matplotlib.figure.FigureBase.subfigure_mosaic:6: WARNING: unknown document: '/gallery/subplots_axes_and_figures/subfig_mosaic'

This look related to this PR.

I took the liberty of rebasing this again + a few little fix ups at it seems to work.

I thought I was going to needget_figure(root=False) but it turns out I did not so dropped that commit.