matplotlib · tacaswell · Oct 21, 2022 · Oct 16, 2022 · Oct 16, 2022 · Oct 16, 2022
diff --git a/doc/api/next_api_changes/behavior/24189-JB.rst b/doc/api/next_api_changes/behavior/24189-JB.rst
@@ -0,0 +1,10 @@
+``fig.subplot_mosaic`` no longer passes the ``gridspec_kw`` args to nested gridspecs.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For nested `.Figure.subplot_mosaic` layouts, it is almost always
+inappropriate for *gridspec_kw* arguments to be passed to lower nest
+levels, and these arguments are incompatible with the lower levels in
+many cases. This dictionary is no longer passed to the inner
+layouts. Users who need to modify *gridspec_kw* at multiple levels
+should use `.Figure.subfigures` to get nesting, and construct the
+inner layouts with `.Figure.subplots` or `.Figure.subplot_mosaic`.
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -1838,21 +1838,26 @@ def subplot_mosaic(self, mosaic, *, sharex=False, sharey=False,
             Defines the relative widths of the columns. Each column gets a
             relative width of ``width_ratios[i] / sum(width_ratios)``.
             If not given, all columns will have the same width.  Equivalent
-            to ``gridspec_kw={'width_ratios': [...]}``.
+            to ``gridspec_kw={'width_ratios': [...]}``. In the case of nested
+            layouts, this argument applies only to the outer layout.
 
         height_ratios : array-like of length *nrows*, optional
             Defines the relative heights of the rows. Each row gets a
             relative height of ``height_ratios[i] / sum(height_ratios)``.
             If not given, all rows will have the same height. Equivalent
-            to ``gridspec_kw={'height_ratios': [...]}``.
+            to ``gridspec_kw={'height_ratios': [...]}``. In the case of nested
+            layouts, this argument applies only to the outer layout.
 
         subplot_kw : dict, optional
             Dictionary with keywords passed to the `.Figure.add_subplot` call
             used to create each subplot.
 
         gridspec_kw : dict, optional
             Dictionary with keywords passed to the `.GridSpec` constructor used
-            to create the grid the subplots are placed on.
+            to create the grid the subplots are placed on. In the case of
+            nested layouts, this argument applies only to the outer layout.
+            For more complex layouts, users should use `.Figure.subfigures`
+            to create the nesting.
 
         empty_sentinel : object, optional
             Entry in the layout to mean "leave this space empty".  Defaults
@@ -2022,7 +2027,7 @@ def _do_layout(gs, mosaic, unique_ids, nested):
                     # recursively add the nested mosaic
                     rows, cols = nested_mosaic.shape
                     nested_output = _do_layout(
-                        gs[j, k].subgridspec(rows, cols, **gridspec_kw),
+                        gs[j, k].subgridspec(rows, cols),
                         nested_mosaic,
                         *_identify_keys_and_nested(nested_mosaic)
                     )

diff --git a/lib/matplotlib/tests/test_figure.py b/lib/matplotlib/tests/test_figure.py
@@ -922,6 +922,26 @@ def test_nested_tuple(self, fig_test, fig_ref):
         fig_ref.subplot_mosaic([["F"], [x]])
         fig_test.subplot_mosaic([["F"], [xt]])
 
+    def test_nested_width_ratios(self):
+        x = [["A", [["B"],
+                    ["C"]]]]
+        width_ratios = [2, 1]
+
+        fig, axd = plt.subplot_mosaic(x, width_ratios=width_ratios)
+
+        assert axd["A"].get_gridspec().get_width_ratios() == width_ratios
+        assert axd["B"].get_gridspec().get_width_ratios() != width_ratios
+
+    def test_nested_height_ratios(self):
+        x = [["A", [["B"],
+                    ["C"]]], ["D", "D"]]
+        height_ratios = [1, 2]
+
+        fig, axd = plt.subplot_mosaic(x, height_ratios=height_ratios)
+
+        assert axd["D"].get_gridspec().get_height_ratios() == height_ratios
+        assert axd["B"].get_gridspec().get_height_ratios() != height_ratios
+
     @check_figures_equal(extensions=["png"])
     @pytest.mark.parametrize(
         "x, empty_sentinel",