WARN: Add FutureWarning for DataFrame.to_latex (#44411)

Co-authored-by: JHM Darbyshire (iMac) <[email protected]>

doc/source/whatsnew/v1.2.0.rst

@@ -150,6 +150,7 @@ and a short caption (:issue:`36267`).
 The keyword ``position`` has been added to set the position.
 
 .. ipython:: python
+   :okwarning:
 
    data = pd.DataFrame({'a': [1, 2], 'b': [3, 4]})
    table = data.to_latex(position='ht')
@@ -161,6 +162,7 @@ one can optionally provide a tuple ``(full_caption, short_caption)``
 to add a short caption macro.
 
 .. ipython:: python
+   :okwarning:
 
    data = pd.DataFrame({'a': [1, 2], 'b': [3, 4]})
    table = data.to_latex(caption=('the full long caption', 'short caption'))

doc/source/whatsnew/v1.4.0.rst

@@ -466,6 +466,7 @@ Other Deprecations
 - Deprecated the 'errors' keyword argument in :meth:`Series.where`, :meth:`DataFrame.where`, :meth:`Series.mask`, and meth:`DataFrame.mask`; in a future version the argument will be removed (:issue:`44294`)
 - Deprecated :meth:`PeriodIndex.astype` to ``datetime64[ns]`` or ``DatetimeTZDtype``, use ``obj.to_timestamp(how).tz_localize(dtype.tz)`` instead (:issue:`44398`)
 - Deprecated :meth:`DateOffset.apply`, use ``offset + other`` instead (:issue:`44522`)
+- A deprecation warning is now shown for :meth:`DataFrame.to_latex` indicating the arguments signature may change and emulate more the arguments to :meth:`.Styler.to_latex` in future versions (:issue:`44411`)
 -
 
 .. ---------------------------------------------------------------------------

pandas/core/generic.py

@@ -3272,6 +3272,7 @@ def to_latex(
         {returns}
         See Also
         --------
+        Styler.to_latex : Render a DataFrame to LaTeX with conditional formatting.
         DataFrame.to_string : Render a DataFrame to a console-friendly
             tabular output.
         DataFrame.to_html : Render a DataFrame as an HTML table.
@@ -3281,7 +3282,7 @@ def to_latex(
         >>> df = pd.DataFrame(dict(name=['Raphael', 'Donatello'],
         ...                   mask=['red', 'purple'],
         ...                   weapon=['sai', 'bo staff']))
-        >>> print(df.to_latex(index=False))  # doctest: +NORMALIZE_WHITESPACE
+        >>> print(df.to_latex(index=False))  # doctest: +SKIP
         \begin{{tabular}}{{lll}}
          \toprule
                name &    mask &    weapon \\
@@ -3291,6 +3292,15 @@ def to_latex(
         \bottomrule
         \end{{tabular}}
         """
+        msg = (
+            "In future versions `DataFrame.to_latex` is expected to utilise the base "
+            "implementation of `Styler.to_latex` for formatting and rendering. "
+            "The arguments signature may therefore change. It is recommended instead "
+            "to use `DataFrame.style.to_latex` which also contains additional "
+            "functionality."
+        )
+        warnings.warn(msg, FutureWarning, stacklevel=find_stack_level())
+
         # Get defaults from the pandas config
         if self.ndim == 1:
             self = self.to_frame()

pandas/tests/frame/test_repr_info.py

@@ -265,6 +265,7 @@ def test_repr_column_name_unicode_truncation_bug(self):
         with option_context("display.max_columns", 20):
             assert "StringCol" in repr(df)
 
+    @pytest.mark.filterwarnings("ignore::FutureWarning")
     def test_latex_repr(self):
         result = r"""\begin{tabular}{llll}
 \toprule

pandas/tests/io/formats/test_format.py

@@ -3298,6 +3298,7 @@ def test_repr_html_ipython_config(ip):
     assert not result.error_in_exec
 
 
+@pytest.mark.filterwarnings("ignore:In future versions `DataFrame.to_latex`")
 @pytest.mark.parametrize("method", ["to_string", "to_html", "to_latex"])
 @pytest.mark.parametrize(
     "encoding, data",
@@ -3319,7 +3320,8 @@ def test_filepath_or_buffer_arg(
         ):
             getattr(df, method)(buf=filepath_or_buffer, encoding=encoding)
     elif encoding == "foo":
-        with tm.assert_produces_warning(None):
+        expected_warning = FutureWarning if method == "to_latex" else None
+        with tm.assert_produces_warning(expected_warning):
             with pytest.raises(LookupError, match="unknown encoding"):
                 getattr(df, method)(buf=filepath_or_buffer, encoding=encoding)
     else:
@@ -3328,6 +3330,7 @@ def test_filepath_or_buffer_arg(
         assert_filepath_or_buffer_equals(expected)
 
 
+@pytest.mark.filterwarnings("ignore::FutureWarning")
 @pytest.mark.parametrize("method", ["to_string", "to_html", "to_latex"])
 def test_filepath_or_buffer_bad_arg_raises(float_frame, method):
     msg = "buf is not a file name and it has no write method"

pandas/tests/io/formats/test_to_latex.py

@@ -19,6 +19,8 @@
     RowStringConverter,
 )
 
+pytestmark = pytest.mark.filterwarnings("ignore::FutureWarning")
+
 
 def _dedent(string):
     """Dedent without new line in the beginning.
@@ -1514,3 +1516,15 @@ def test_get_strrow_multindex_multicolumn(self, row_num, expected):
         )
 
         assert row_string_converter.get_strrow(row_num=row_num) == expected
+
+    def test_future_warning(self):
+        df = DataFrame([[1]])
+        msg = (
+            "In future versions `DataFrame.to_latex` is expected to utilise the base "
+            "implementation of `Styler.to_latex` for formatting and rendering. "
+            "The arguments signature may therefore change. It is recommended instead "
+            "to use `DataFrame.style.to_latex` which also contains additional "
+            "functionality."
+        )
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            df.to_latex()

pandas/tests/io/test_common.py

@@ -348,6 +348,7 @@ def test_read_fspath_all(self, reader, module, path, datapath):
         else:
             tm.assert_frame_equal(result, expected)
 
+    @pytest.mark.filterwarnings("ignore:In future versions `DataFrame.to_latex`")
     @pytest.mark.parametrize(
         "writer_name, writer_kwargs, module",
         [

pandas/tests/series/test_repr.py

@@ -196,6 +196,7 @@ def test_timeseries_repr_object_dtype(self):
         ts2 = ts.iloc[np.random.randint(0, len(ts) - 1, 400)]
         repr(ts2).splitlines()[-1]
 
+    @pytest.mark.filterwarnings("ignore::FutureWarning")
     def test_latex_repr(self):
         result = r"""\begin{tabular}{ll}
 \toprule