ENH: Enable short_caption in to_latex

pandas/core/generic.py

@@ -2887,7 +2887,8 @@ def to_latex(
         multicolumn=None,
         multicolumn_format=None,
         multirow=None,
-        caption=None,
+        caption: Optional[Union[str, Tuple[str, str]]] = None,
+        short_caption=None,
         label=None,
         position=None,
     ):
@@ -2965,11 +2966,12 @@ def to_latex(
             centered labels (instead of top-aligned) across the contained
             rows, separating groups via clines. The default will be read
             from the pandas config module.
-        caption : str, optional
-            The LaTeX caption to be placed inside ``\caption{}`` in the output.
+        caption : str, tuple, optional
+            Tuple (short_caption, full_caption),
+            which results in \caption[short_caption]{caption};
+            if a single string is passed, no short caption will be set.
 
             .. versionadded:: 1.0.0
-
         label : str, optional
             The LaTeX label to be placed inside ``\label{}`` in the output.
             This is used with ``\ref{}`` in the main ``.tex`` file.
@@ -3014,6 +3016,18 @@ def to_latex(
         if multirow is None:
             multirow = config.get_option("display.latex.multirow")
 
+        if caption:
+            if isinstance(caption, str):
+                short_caption = ""
+            else:
+                try:
+                    caption, short_caption = caption
+                except ValueError as err:
+                    msg = "caption must be either str or tuple of two strings"
+                    raise ValueError(msg) from err
+        else:
+            short_caption = None
+
         formatter = DataFrameFormatter(
             self,
             columns=columns,
@@ -3038,6 +3052,7 @@ def to_latex(
             multicolumn_format=multicolumn_format,
             multirow=multirow,
             caption=caption,
+            short_caption=short_caption,
             label=label,
             position=position,
         )

pandas/io/formats/format.py

@@ -930,6 +930,7 @@ def to_latex(
         multicolumn_format: Optional[str] = None,
         multirow: bool = False,
         caption: Optional[str] = None,
+        short_caption: Optional[str] = None,
         label: Optional[str] = None,
         position: Optional[str] = None,
     ) -> Optional[str]:
@@ -946,6 +947,7 @@ def to_latex(
             multicolumn_format=multicolumn_format,
             multirow=multirow,
             caption=caption,
+            short_caption=short_caption,
             label=label,
             position=position,
         ).get_result(buf=buf, encoding=encoding)

pandas/io/formats/latex.py

@@ -37,6 +37,7 @@ def __init__(
         multicolumn_format: Optional[str] = None,
         multirow: bool = False,
         caption: Optional[str] = None,
+        short_caption: Optional[str] = None,
         label: Optional[str] = None,
         position: Optional[str] = None,
     ):
@@ -49,6 +50,7 @@ def __init__(
         self.multicolumn_format = multicolumn_format
         self.multirow = multirow
         self.caption = caption
+        self.short_caption = short_caption
         self.label = label
         self.escape = self.fmt.escape
         self.position = position
@@ -283,15 +285,8 @@ def _write_tabular_begin(self, buf, column_format: str):
         """
         if self._table_float:
             # then write output in a nested table/tabular or longtable environment
-            if self.caption is None:
-                caption_ = ""
-            else:
-                caption_ = f"\n\\caption{{{self.caption}}}"
-
-            if self.label is None:
-                label_ = ""
-            else:
-                label_ = f"\n\\label{{{self.label}}}"
+            caption_ = self._compose_caption_macro()
+            label_ = self._compose_label_macro()
 
             if self.position is None:
                 position_ = ""
@@ -339,5 +334,16 @@ def _write_tabular_end(self, buf):
             buf.write("\\end{tabular}\n")
             if self._table_float:
                 buf.write("\\end{table}\n")
-            else:
-                pass
+
+    def _compose_caption_macro(self):
+        if self.caption is None:
+            return ""
+        if self.short_caption:
+            return f"\n\\caption[{self.short_caption}]{{{self.caption}}}"
+        return f"\n\\caption{{{self.caption}}}"
+
+    def _compose_label_macro(self):
+        if self.label is None:
+            return ""
+        else:
+            return f"\n\\label{{{self.label}}}"

pandas/tests/io/formats/test_to_latex.py

@@ -441,6 +441,7 @@ def test_to_latex_longtable(self):
     def test_to_latex_caption_label(self):
         # GH 25436
         the_caption = "a table in a \\texttt{table/tabular} environment"
+        the_short_caption = "a table"
         the_label = "tab:table_tabular"
 
         df = DataFrame({"a": [1, 2], "b": ["b1", "b2"]})
@@ -497,12 +498,73 @@ def test_to_latex_caption_label(self):
 \bottomrule
 \end{tabular}
 \end{table}
+"""
+        assert result_cl == expected_cl
+
+        # test when the short_caption is provided alongside caption
+        result_cl = df.to_latex(caption=(the_caption, the_short_caption))
+
+        expected_cl = r"""\begin{table}
+\centering
+\caption[a table]{a table in a \texttt{table/tabular} environment}
+\begin{tabular}{lrl}
+\toprule
+{} &  a &   b \\
+\midrule
+0 &  1 &  b1 \\
+1 &  2 &  b2 \\
+\bottomrule
+\end{tabular}
+\end{table}
+"""
+        assert result_cl == expected_cl
+
+        # test when the short_caption is provided alongside caption and label
+        result_cl = df.to_latex(
+            caption=(the_caption, the_short_caption), label=the_label,
+        )
+
+        expected_cl = r"""\begin{table}
+\centering
+\caption[a table]{a table in a \texttt{table/tabular} environment}
+\label{tab:table_tabular}
+\begin{tabular}{lrl}
+\toprule
+{} &  a &   b \\
+\midrule
+0 &  1 &  b1 \\
+1 &  2 &  b2 \\
+\bottomrule
+\end{tabular}
+\end{table}
+"""
+        assert result_cl == expected_cl
+
+        # test that wrong number of params is raised
+        with pytest.raises(ValueError):
+            df.to_latex(caption=(the_caption, the_short_caption, "extra_string"))
+
+        # test that two chars caption is handled correctly
+        result_cl = df.to_latex(caption="xy")
+        expected_cl = r"""\begin{table}
+\centering
+\caption{xy}
+\begin{tabular}{lrl}
+\toprule
+{} &  a &   b \\
+\midrule
+0 &  1 &  b1 \\
+1 &  2 &  b2 \\
+\bottomrule
+\end{tabular}
+\end{table}
 """
         assert result_cl == expected_cl
 
     def test_to_latex_longtable_caption_label(self):
         # GH 25436
         the_caption = "a table in a \\texttt{longtable} environment"
+        the_short_caption = "a table"
         the_label = "tab:longtable"
 
         df = DataFrame({"a": [1, 2], "b": ["b1", "b2"]})
@@ -566,6 +628,31 @@ def test_to_latex_longtable_caption_label(self):
 \midrule
 \endfoot
 
+\bottomrule
+\endlastfoot
+0 &  1 &  b1 \\
+1 &  2 &  b2 \\
+\end{longtable}
+"""
+        assert result_cl == expected_cl
+
+        # test when the caption, the short_caption and the label are provided
+        result_cl = df.to_latex(
+            longtable=True, caption=(the_caption, the_short_caption), label=the_label,
+        )
+
+        expected_cl = r"""\begin{longtable}{lrl}
+\caption[a table]{a table in a \texttt{longtable} environment}
+\label{tab:longtable}\\
+\toprule
+{} &  a &   b \\
+\midrule
+\endhead
+\midrule
+\multicolumn{3}{r}{{Continued on next page}} \\
+\midrule
+\endfoot
+
 \bottomrule
 \endlastfoot
 0 &  1 &  b1 \\