ENH: add long and short captions to Styler.to_latex

pandas/io/formats/style.py

@@ -87,8 +87,8 @@ class Styler(StylerRenderer):
         List of {selector: (attr, value)} dicts; see Notes.
     uuid : str, default None
         A unique identifier to avoid CSS collisions; generated automatically.
-    caption : str, default None
-        Caption to attach to the table.
+    caption : str, tuple, default None
+        String caption to attach to the table. Tuple only used for LaTeX dual captions.
     table_attributes : str, default None
         Items that show up in the opening ``<table>`` tag
         in addition to automatic (by default) id.
@@ -172,7 +172,7 @@ def __init__(
         precision: int | None = None,
         table_styles: CSSStyles | None = None,
         uuid: str | None = None,
-        caption: str | None = None,
+        caption: str | tuple | None = None,
         table_attributes: str | None = None,
         cell_ids: bool = True,
         na_rep: str | None = None,
@@ -416,7 +416,7 @@ def to_latex(
         position_float: str | None = None,
         hrules: bool = False,
         label: str | None = None,
-        caption: str | None = None,
+        caption: str | tuple | None = None,
         sparse_index: bool | None = None,
         sparse_columns: bool | None = None,
         multirow_align: str = "c",
@@ -457,8 +457,9 @@ def to_latex(
         label : str, optional
             The LaTeX label included as: \\label{<label>}.
             This is used with \\ref{<label>} in the main .tex file.
-        caption : str, optional
-            The LaTeX table caption included as: \\caption{<caption>}.
+        caption : str, tuple, optional
+            If string, the LaTeX table caption included as: \\caption{<caption>}.
+            If tuple, the caption included as: \\caption[<caption[0]>]{<caption[1]>}.
         sparse_index : bool, optional
             Whether to sparsify the display of a hierarchical index. Setting to False
             will display each explicit level element in a hierarchical key for each row.
@@ -1273,13 +1274,15 @@ def set_uuid(self, uuid: str) -> Styler:
         self.uuid = uuid
         return self
 
-    def set_caption(self, caption: str) -> Styler:
+    def set_caption(self, caption: str | tuple) -> Styler:
         """
         Set the text added to a ``<caption>`` HTML element.
 
         Parameters
         ----------
-        caption : str
+        caption : str, tuple
+            For HTML output only string input is used, for LaTeX the additional
+            tuple input allows for short and long captions.
 
         Returns
         -------

pandas/io/formats/style_render.py

@@ -75,7 +75,7 @@ def __init__(
         uuid_len: int = 5,
         table_styles: CSSStyles | None = None,
         table_attributes: str | None = None,
-        caption: str | None = None,
+        caption: str | tuple | None = None,
         cell_ids: bool = True,
     ):
 

pandas/io/formats/templates/html.tpl

@@ -27,7 +27,7 @@
 {% block table %}
 <table id="T_{{uuid}}"{% if table_attributes %} {{table_attributes}}{% endif %}>
 {% block caption %}
-{% if caption %}
+{% if caption and caption is string %}
   <caption>{{caption}}</caption>
 {% endif %}
 {% endblock caption %}

pandas/io/formats/templates/latex.tpl

@@ -9,9 +9,12 @@
 {% if position_float is not none%}
 \{{position_float}}
 {% endif %}
-{% if caption %}
+{% if caption and caption is string %}
 \caption{% raw %}{{% endraw %}{{caption}}{% raw %}}{% endraw %}
 
+{% elif caption and caption is sequence %}
+\caption[{{caption[0]}}]{% raw %}{{% endraw %}{{caption[1]}}{% raw %}}{% endraw %}
+
 {% endif %}
 {% for style in table_styles %}
 {% if style['selector'] not in ['position', 'position_float', 'caption', 'toprule', 'midrule', 'bottomrule', 'column_format'] %}

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

@@ -1502,3 +1502,8 @@ def test_from_custom_template(tmpdir):
     assert result.template_html is not Styler.template_html
     styler = result(DataFrame({"A": [1, 2]}))
     assert styler.render()
+
+
+def test_caption_no_sequence(mi_styler):
+    mi_styler.set_caption(("short cap", "long_cap"))
+    assert "<caption>" not in mi_styler.render()

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

@@ -438,3 +438,8 @@ def test_parse_latex_table_wrapping(styler):
         overwrite=False,
     )
     assert _parse_latex_table_wrapping(styler.table_styles, None) is True
+
+
+def test_long_captions(styler):
+    result = styler.to_latex(caption=("short cap", "long cap"))
+    assert "\\caption[short cap]{long cap}" in result