diff --git a/doc/source/whatsnew/v1.2.0.rst b/doc/source/whatsnew/v1.2.0.rst index 36b591c3c3142..3d3ec53948a01 100644 --- a/doc/source/whatsnew/v1.2.0.rst +++ b/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')) diff --git a/doc/source/whatsnew/v1.4.0.rst b/doc/source/whatsnew/v1.4.0.rst index 7270227e113da..d88add84d188d 100644 --- a/doc/source/whatsnew/v1.4.0.rst +++ b/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`) - .. --------------------------------------------------------------------------- diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 91216ef03c8b3..2215c39163b9a 100644 --- a/pandas/core/generic.py +++ b/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() diff --git a/pandas/tests/frame/test_repr_info.py b/pandas/tests/frame/test_repr_info.py index b288fafd8f7f6..bb80bd12c1958 100644 --- a/pandas/tests/frame/test_repr_info.py +++ b/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 diff --git a/pandas/tests/io/formats/test_format.py b/pandas/tests/io/formats/test_format.py index d9bd8f6809c73..ab0199dca3f24 100644 --- a/pandas/tests/io/formats/test_format.py +++ b/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" diff --git a/pandas/tests/io/formats/test_to_latex.py b/pandas/tests/io/formats/test_to_latex.py index 10c8ccae67fb2..01bc94bf594d9 100644 --- a/pandas/tests/io/formats/test_to_latex.py +++ b/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() diff --git a/pandas/tests/io/test_common.py b/pandas/tests/io/test_common.py index 5f1256c4e5ba3..a782f8dbbc76d 100644 --- a/pandas/tests/io/test_common.py +++ b/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", [ diff --git a/pandas/tests/series/test_repr.py b/pandas/tests/series/test_repr.py index d3ff7f4dc7b4c..de34caa7b4387 100644 --- a/pandas/tests/series/test_repr.py +++ b/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