BUG: styler.concat should raise when index nlevels are incompatible

pandas/io/formats/style.py

@@ -281,7 +281,8 @@ def concat(self, other: Styler) -> Styler:
         ----------
         other : Styler
             The other Styler object which has already been styled and formatted. The
-            data for this Styler must have the same columns as the original.
+            data for this Styler must have the same columns as the original, and the
+            number of index levels must also be the same to render correctly.
 
         Returns
         -------
@@ -344,11 +345,24 @@ def concat(self, other: Styler) -> Styler:
         >>> styler.concat(other)  # doctest: +SKIP
 
         .. figure:: ../../_static/style/footer_extended.png
+
+        When ``other`` has fewer index levels than the original Styler it is possible
+        to extend the index in ``other``, with placeholder levels.
+
+        >>> df = DataFrame([[1], [2]], index=pd.MultiIndex.from_product([[0], [1, 2]]))
+        >>> descriptors = df.agg(["sum"])
+        >>> descriptors.index = pd.MultiIndex.from_product([[""], descriptors.index])
+        >>> df.style.concat(descriptors.style)  # doctest: +SKIP
         """
         if not isinstance(other, Styler):
             raise TypeError("`other` must be of type `Styler`")
         if not self.data.columns.equals(other.data.columns):
             raise ValueError("`other.data` must have same columns as `Styler.data`")
+        if not self.data.index.nlevels == other.data.index.nlevels:
+            raise ValueError(
+                "number of index levels must be same in `other` "
+                "as in `Styler`. See documentation for suggestions."
+            )
         self.concatenated = other
         return self
 

pandas/tests/io/formats/style/test_exceptions.py

@@ -2,7 +2,10 @@
 
 jinja2 = pytest.importorskip("jinja2")
 
-from pandas import DataFrame
+from pandas import (
+    DataFrame,
+    MultiIndex,
+)
 
 from pandas.io.formats.style import Styler
 
@@ -31,3 +34,11 @@ def test_concat_bad_type(styler):
     msg = "`other` must be of type `Styler`"
     with pytest.raises(TypeError, match=msg):
         styler.concat(DataFrame([[1, 2]]))
+
+
+def test_concat_bad_index_levels(styler, df):
+    df = df.copy()
+    df.index = MultiIndex.from_tuples([(0, 0), (1, 1)])
+    msg = "number of index levels must be same in `other`"
+    with pytest.raises(ValueError, match=msg):
+        styler.concat(df.style)

pandas/tests/io/formats/style/test_style.py

@@ -56,7 +56,9 @@ def mi_styler_comp(mi_styler):
     mi_styler.hide(axis="index")
     mi_styler.hide([("i0", "i1_a")], axis="index", names=True)
     mi_styler.set_table_attributes('class="box"')
-    mi_styler.concat(mi_styler.data.agg(["mean"]).style)
+    other = mi_styler.data.agg(["mean"])
+    other.index = MultiIndex.from_product([[""], other.index])
+    mi_styler.concat(other.style)
     mi_styler.format(na_rep="MISSING", precision=3)
     mi_styler.format_index(precision=2, axis=0)
     mi_styler.format_index(precision=4, axis=1)