ENH: add environment, e.g. "longtable", to Styler.to_latex

pandas/io/formats/style.py

@@ -425,6 +425,7 @@ def to_latex(
         multirow_align: str = "c",
         multicol_align: str = "r",
         siunitx: bool = False,
+        environment: str | None = None,
         encoding: str | None = None,
     ):
         r"""
@@ -480,6 +481,10 @@ def to_latex(
             the left, centrally, or at the right.
         siunitx : bool, default False
             Set to ``True`` to structure LaTeX compatible with the {siunitx} package.
+        environment : str, optional
+            If given the environment that will replace 'table' in ``\\begin{table}``.
+            If 'longtable' is specified then a custom, more suitable template, will be
+            rendered where the argument ``position_float`` has no effect.
         encoding : str, default "utf-8"
             Character encoding setting.
 
@@ -740,6 +745,7 @@ def to_latex(
             sparse_columns=sparse_columns,
             multirow_align=multirow_align,
             multicol_align=multicol_align,
+            environment=environment,
         )
 
         return save_to_buffer(latex, buf=buf, encoding=encoding)

pandas/io/formats/templates/latex.tpl

@@ -1,52 +1,5 @@
-{% if parse_wrap(table_styles, caption) %}
-\begin{table}
-{%- set position = parse_table(table_styles, 'position') %}
-{%- if position is not none %}
-[{{position}}]
-{%- endif %}
-
-{% set position_float = parse_table(table_styles, 'position_float') %}
-{% if position_float is not none%}
-\{{position_float}}
-{% endif %}
-{% if caption and caption is string %}
-\caption{% raw %}{{% endraw %}{{caption}}{% raw %}}{% endraw %}
-
-{% elif caption and caption is sequence %}
-\caption[{{caption[1]}}]{% raw %}{{% endraw %}{{caption[0]}}{% raw %}}{% endraw %}
-
-{% endif %}
-{% for style in table_styles %}
-{% if style['selector'] not in ['position', 'position_float', 'caption', 'toprule', 'midrule', 'bottomrule', 'column_format'] %}
-\{{style['selector']}}{{parse_table(table_styles, style['selector'])}}
-{% endif %}
-{% endfor %}
-{% endif %}
-\begin{tabular}
-{%- set column_format = parse_table(table_styles, 'column_format') %}
-{% raw %}{{% endraw %}{{column_format}}{% raw %}}{% endraw %}
-
-{% set toprule = parse_table(table_styles, 'toprule') %}
-{% if toprule is not none %}
-\{{toprule}}
-{% endif %}
-{% for row in head %}
-{% for c in row %}{%- if not loop.first %} & {% endif %}{{parse_header(c, multirow_align, multicol_align, True)}}{% endfor %} \\
-{% endfor %}
-{% set midrule = parse_table(table_styles, 'midrule') %}
-{% if midrule is not none %}
-\{{midrule}}
-{% endif %}
-{% for row in body %}
-{% for c in row %}{% if not loop.first %} & {% endif %}
-  {%- if c.type == 'th' %}{{parse_header(c, multirow_align, multicol_align)}}{% else %}{{parse_cell(c.cellstyle, c.display_value)}}{% endif %}
-{%- endfor %} \\
-{% endfor %}
-{% set bottomrule = parse_table(table_styles, 'bottomrule') %}
-{% if bottomrule is not none %}
-\{{bottomrule}}
-{% endif %}
-\end{tabular}
-{% if parse_wrap(table_styles, caption) %}
-\end{table}
+{% if environment == "longtable" %}
+{% include "latex_longtable.tpl" %}
+{% else %}
+{% include "latex_table.tpl" %}
 {% endif %}

pandas/io/formats/templates/latex_longtable.tpl

@@ -0,0 +1,72 @@
+\begin{longtable}
+{%- set position = parse_table(table_styles, 'position') %}
+{%- if position is not none %}
+[{{position}}]
+{%- endif %}
+{%- set column_format = parse_table(table_styles, 'column_format') %}
+{% raw %}{{% endraw %}{{column_format}}{% raw %}}{% endraw %}
+
+{% for style in table_styles %}
+{% if style['selector'] not in ['position', 'position_float', 'caption', 'toprule', 'midrule', 'bottomrule', 'column_format', 'label'] %}
+\{{style['selector']}}{{parse_table(table_styles, style['selector'])}}
+{% endif %}
+{% endfor %}
+{% if caption and caption is string %}
+\caption{% raw %}{{% endraw %}{{caption}}{% raw %}}{% endraw %}
+{%- set label = parse_table(table_styles, 'label') %}
+{%- if label is not none %}
+ \label{{label}}
+{%- endif %} \\
+{% elif caption and caption is sequence %}
+\caption[{{caption[1]}}]{% raw %}{{% endraw %}{{caption[0]}}{% raw %}}{% endraw %}
+{%- set label = parse_table(table_styles, 'label') %}
+{%- if label is not none %}
+ \label{{label}}
+{%- endif %} \\
+{% endif %}
+{% set toprule = parse_table(table_styles, 'toprule') %}
+{% if toprule is not none %}
+\{{toprule}}
+{% endif %}
+{% for row in head %}
+{% for c in row %}{%- if not loop.first %} & {% endif %}{{parse_header(c, multirow_align, multicol_align, True)}}{% endfor %} \\
+{% endfor %}
+{% set midrule = parse_table(table_styles, 'midrule') %}
+{% if midrule is not none %}
+\{{midrule}}
+{% endif %}
+\endfirsthead
+{% if caption and caption is string %}
+\caption[]{% raw %}{{% endraw %}{{caption}}{% raw %}}{% endraw %} \\
+{% elif caption and caption is sequence %}
+\caption[]{% raw %}{{% endraw %}{{caption[0]}}{% raw %}}{% endraw %} \\
+{% endif %}
+{% if toprule is not none %}
+\{{toprule}}
+{% endif %}
+{% for row in head %}
+{% for c in row %}{%- if not loop.first %} & {% endif %}{{parse_header(c, multirow_align, multicol_align, True)}}{% endfor %} \\
+{% endfor %}
+{% if midrule is not none %}
+\{{midrule}}
+{% endif %}
+\endhead
+{% if midrule is not none %}
+\{{midrule}}
+{% endif %}
+\multicolumn{% raw %}{{% endraw %}{{column_format|length}}{% raw %}}{% endraw %}{r}{Continued on next page} \\
+{% if midrule is not none %}
+\{{midrule}}
+{% endif %}
+\endfoot
+{% set bottomrule = parse_table(table_styles, 'bottomrule') %}
+{% if bottomrule is not none %}
+\{{bottomrule}}
+{% endif %}
+\endlastfoot
+{% for row in body %}
+{% for c in row %}{% if not loop.first %} & {% endif %}
+  {%- if c.type == 'th' %}{{parse_header(c, multirow_align, multicol_align)}}{% else %}{{parse_cell(c.cellstyle, c.display_value)}}{% endif %}
+{%- endfor %} \\
+{% endfor %}
+\end{longtable}

pandas/io/formats/templates/latex_table.tpl

@@ -0,0 +1,53 @@
+{% if environment or parse_wrap(table_styles, caption) %}
+\begin{% raw %}{{% endraw %}{{environment if environment else "table"}}{% raw %}}{% endraw %}
+{%- set position = parse_table(table_styles, 'position') %}
+{%- if position is not none %}
+[{{position}}]
+{%- endif %}
+
+{% set position_float = parse_table(table_styles, 'position_float') %}
+{% if position_float is not none%}
+\{{position_float}}
+{% endif %}
+{% if caption and caption is string %}
+\caption{% raw %}{{% endraw %}{{caption}}{% raw %}}{% endraw %}
+
+{% elif caption and caption is sequence %}
+\caption[{{caption[1]}}]{% raw %}{{% endraw %}{{caption[0]}}{% raw %}}{% endraw %}
+
+{% endif %}
+{% for style in table_styles %}
+{% if style['selector'] not in ['position', 'position_float', 'caption', 'toprule', 'midrule', 'bottomrule', 'column_format'] %}
+\{{style['selector']}}{{parse_table(table_styles, style['selector'])}}
+{% endif %}
+{% endfor %}
+{% endif %}
+\begin{tabular}
+{%- set column_format = parse_table(table_styles, 'column_format') %}
+{% raw %}{{% endraw %}{{column_format}}{% raw %}}{% endraw %}
+
+{% set toprule = parse_table(table_styles, 'toprule') %}
+{% if toprule is not none %}
+\{{toprule}}
+{% endif %}
+{% for row in head %}
+{% for c in row %}{%- if not loop.first %} & {% endif %}{{parse_header(c, multirow_align, multicol_align, True)}}{% endfor %} \\
+{% endfor %}
+{% set midrule = parse_table(table_styles, 'midrule') %}
+{% if midrule is not none %}
+\{{midrule}}
+{% endif %}
+{% for row in body %}
+{% for c in row %}{% if not loop.first %} & {% endif %}
+  {%- if c.type == 'th' %}{{parse_header(c, multirow_align, multicol_align)}}{% else %}{{parse_cell(c.cellstyle, c.display_value)}}{% endif %}
+{%- endfor %} \\
+{% endfor %}
+{% set bottomrule = parse_table(table_styles, 'bottomrule') %}
+{% if bottomrule is not none %}
+\{{bottomrule}}
+{% endif %}
+\end{tabular}
+{% if environment or parse_wrap(table_styles, caption) %}
+\end{% raw %}{{% endraw %}{{environment if environment else "table"}}{% raw %}}{% endraw %}
+
+{% endif %}

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

@@ -443,3 +443,125 @@ def test_parse_latex_table_wrapping(styler):
 def test_short_caption(styler):
     result = styler.to_latex(caption=("full cap", "short cap"))
     assert "\\caption[short cap]{full cap}" in result
+
+
+def test_longtable_comprehensive(styler):
+    result = styler.to_latex(
+        environment="longtable", hrules=True, label="fig:A", caption=("full", "short")
+    )
+    assert result == dedent(
+        """\
+        \\begin{longtable}{lrrl}
+        \\caption[short]{full} \\label{fig:A} \\\\
+        \\toprule
+        {} & {A} & {B} & {C} \\\\
+        \\midrule
+        \\endfirsthead
+        \\caption[]{full} \\\\
+        \\toprule
+        {} & {A} & {B} & {C} \\\\
+        \\midrule
+        \\endhead
+        \\midrule
+        \\multicolumn{4}{r}{Continued on next page} \\\\
+        \\midrule
+        \\endfoot
+        \\bottomrule
+        \\endlastfoot
+        0 & 0 & -0.61 & ab \\\\
+        1 & 1 & -1.22 & cd \\\\
+        \\end{longtable}"""
+    )
+
+
+def test_longtable_minimal(styler):
+    result = styler.to_latex(environment="longtable")
+    assert result == dedent(
+        """\
+        \\begin{longtable}{lrrl}
+        {} & {A} & {B} & {C} \\\\
+        \\endfirsthead
+        {} & {A} & {B} & {C} \\\\
+        \\endhead
+        \\multicolumn{4}{r}{Continued on next page} \\\\
+        \\endfoot
+        \\endlastfoot
+        0 & 0 & -0.61 & ab \\\\
+        1 & 1 & -1.22 & cd \\\\
+        \\end{longtable}"""
+    )
+
+
+def test_longtable_multiindex_columns(df):
+    cidx = MultiIndex.from_tuples([("A", "a"), ("A", "b"), ("B", "c")])
+    df.columns = cidx
+    expected = dedent(
+        """\
+        \\begin{longtable}{lrrl}
+        {} & \\multicolumn{2}{r}{A} & {B} \\\\
+        {} & {a} & {b} & {c} \\\\
+        \\endfirsthead
+        {} & \\multicolumn{2}{r}{A} & {B} \\\\
+        {} & {a} & {b} & {c} \\\\
+        \\endhead
+        """
+    )
+    assert expected in df.style.to_latex(environment="longtable")
+
+    # non-sparse
+    expected = dedent(
+        """\
+        \\begin{longtable}{lrrl}
+        {} & {A} & {A} & {B} \\\\
+        {} & {a} & {b} & {c} \\\\
+        \\endfirsthead
+        {} & {A} & {A} & {B} \\\\
+        {} & {a} & {b} & {c} \\\\
+        \\endhead
+        """
+    )
+    assert expected in df.style.to_latex(environment="longtable", sparse_columns=False)
+
+
+def test_longtable_caption_label(styler):
+    expected = dedent(
+        """\
+        \\caption{full} \\\\
+        {} & {A} & {B} & {C} \\\\
+        \\endfirsthead
+        \\caption[]{full} \\\\
+        """
+    )
+    assert expected in styler.to_latex(environment="longtable", caption="full")
+
+    expected = dedent(
+        """\
+        \\caption[short]{full} \\label{fig:A} \\\\
+        {} & {A} & {B} & {C} \\\\
+        \\endfirsthead
+        \\caption[]{full} \\\\
+        """
+    )
+    assert expected in styler.to_latex(
+        environment="longtable", caption=("full", "short"), label="fig:A"
+    )
+
+    expected = dedent(
+        """\
+        \\caption{full} \\label{fig:A} \\\\
+        {} & {A} & {B} & {C} \\\\
+        \\endfirsthead
+        \\caption[]{full} \\\\
+        """
+    )
+    assert expected in styler.to_latex(
+        environment="longtable", caption="full", label="fig:A"
+    )
+
+
+def test_latex_environment(styler):
+    result = styler.to_latex(environment="figure*")
+    assert "\\begin{table}" not in result
+    assert "\\end{table}" not in result
+    assert "\\begin{figure*}" in result
+    assert "\\end{figure*}" in result