ENH: .to_latex(longtable=True) latex caption and label support

pandas/core/generic.py

@@ -2740,9 +2740,9 @@ class      (index) object 'bird' 'bird' 'mammal' 'mammal'
     def to_latex(self, buf=None, columns=None, col_space=None, header=True,
                  index=True, na_rep='NaN', formatters=None, float_format=None,
                  sparsify=None, index_names=True, bold_rows=False,
-                 column_format=None, longtable=None, escape=None,
-                 encoding=None, decimal='.', multicolumn=None,
-                 multicolumn_format=None, multirow=None):
+                 column_format=None, longtable=None, lt_caption=None,
+                 lt_label=None, escape=None, encoding=None, decimal='.',
+                 multicolumn=None, multicolumn_format=None, multirow=None):
         r"""
         Render an object to a LaTeX tabular environment table.
 
@@ -2790,6 +2790,10 @@ def to_latex(self, buf=None, columns=None, col_space=None, header=True,
             By default, the value will be read from the pandas config
             module. Use a longtable environment instead of tabular. Requires
             adding a \usepackage{longtable} to your LaTeX preamble.
+        lt_caption : str, optional
+            The caption to use when longtable is True
+        lt_label : str, optional
+            The label to use with \ref{} when longtable is True
         escape : bool, optional
             By default, the value will be read from the pandas config
             module. When set to False prevents from escaping latex special
@@ -2863,6 +2867,7 @@ def to_latex(self, buf=None, columns=None, col_space=None, header=True,
                                        index_names=index_names,
                                        escape=escape, decimal=decimal)
         formatter.to_latex(column_format=column_format, longtable=longtable,
+                           lt_caption=lt_caption, lt_label=lt_label,
                            encoding=encoding, multicolumn=multicolumn,
                            multicolumn_format=multicolumn_format,
                            multirow=multirow)

pandas/io/formats/format.py

@@ -679,15 +679,18 @@ def _join_multiline(self, *strcols):
             st = ed
         return '\n\n'.join(str_lst)
 
-    def to_latex(self, column_format=None, longtable=False, encoding=None,
-                 multicolumn=False, multicolumn_format=None, multirow=False):
+    def to_latex(self, column_format=None, longtable=False, lt_caption=None,
+                 lt_label=None, encoding=None, multicolumn=False,
+                 multicolumn_format=None, multirow=False):
         """
         Render a DataFrame to a LaTeX tabular/longtable environment output.
         """
 
         from pandas.io.formats.latex import LatexFormatter
         latex_renderer = LatexFormatter(self, column_format=column_format,
                                         longtable=longtable,
+                                        lt_caption=lt_caption,
+                                        lt_label=lt_label,
                                         multicolumn=multicolumn,
                                         multicolumn_format=multicolumn_format,
                                         multirow=multirow)

pandas/io/formats/latex.py

@@ -4,6 +4,8 @@
 """
 from __future__ import print_function
 
+from warnings import warn
+
 import numpy as np
 
 from pandas.compat import map, range, u, zip
@@ -34,12 +36,15 @@ class LatexFormatter(TableFormatter):
     """
 
     def __init__(self, formatter, column_format=None, longtable=False,
-                 multicolumn=False, multicolumn_format=None, multirow=False):
+                 lt_caption=None, lt_label=None, multicolumn=False,
+                 multicolumn_format=None, multirow=False):
         self.fmt = formatter
         self.frame = self.fmt.frame
         self.bold_rows = self.fmt.kwds.get('bold_rows', False)
         self.column_format = column_format
         self.longtable = longtable
+        self.lt_caption = lt_caption
+        self.lt_label = lt_label
         self.multicolumn = multicolumn
         self.multicolumn_format = multicolumn_format
         self.multirow = multirow
@@ -113,6 +118,26 @@ def pad_empties(x):
         else:
             buf.write('\\begin{{longtable}}{{{fmt}}}\n'
                       .format(fmt=column_format))
+
+            if self.lt_caption is None and self.lt_label is None:
+                pass
+            else:
+                if self.lt_caption is not None:
+                    buf.write('\\caption{{{}}}'.format(self.lt_caption))
+                else:
+                    pass
+
+                if self.lt_label is not None:
+                    buf.write('\\label{{{}}}'.format(self.lt_label))
+                else:
+                    warn('no LaTeX label has been provided; '
+                         'referencing with \\ref{} will not work')
+
+                # a double-backslash is required at the end of the line
+                # as discussed here:
+                # https://tex.stackexchange.com/questions/219138
+                buf.write('\\\\\n')
+
             buf.write('\\toprule\n')
 
         ilevels = self.frame.index.nlevels