WARN: Add FutureWarning to DataFrame.to_html

doc/source/user_guide/io.rst

@@ -21,7 +21,7 @@ The pandas I/O API is a set of top level ``reader`` functions accessed like
     text;`CSV <https://en.wikipedia.org/wiki/Comma-separated_values>`__;:ref:`read_csv<io.read_csv_table>`;:ref:`to_csv<io.store_in_csv>`
     text;Fixed-Width Text File;:ref:`read_fwf<io.fwf_reader>`
     text;`JSON <https://www.json.org/>`__;:ref:`read_json<io.json_reader>`;:ref:`to_json<io.json_writer>`
-    text;`HTML <https://en.wikipedia.org/wiki/HTML>`__;:ref:`read_html<io.read_html>`;:ref:`to_html<io.html>`
+    text;`HTML <https://en.wikipedia.org/wiki/HTML>`__;:ref:`read_html<io.read_html>`;:ref:`Styler.to_html<io.html>`
     text;`LaTeX <https://en.wikipedia.org/wiki/LaTeX>`__;;:ref:`Styler.to_latex<io.latex>`
     text;`XML <https://www.w3.org/standards/xml/core>`__;:ref:`read_xml<io.read_xml>`;:ref:`to_xml<io.xml>`
     text; Local clipboard;:ref:`read_clipboard<io.clipboard>`;:ref:`to_clipboard<io.clipboard>`
@@ -2633,8 +2633,8 @@ Read in pandas ``to_html`` output (with some loss of floating point precision):
 .. code-block:: python
 
    df = pd.DataFrame(np.random.randn(2, 2))
-   s = df.to_html(float_format="{0:.40g}".format)
-   dfin = pd.read_html(s, index_col=0)
+   s = df.style.format("{0:.40g}").to_html()
+   dfin = pd.read_html(s, index_col=0)[0]
 
 The ``lxml`` backend will raise an error on a failed parse if that is the only
 parser you provide. If you only have a single parser you can provide just a
@@ -2665,156 +2665,34 @@ succeeds, the function will return*.
 Writing to HTML files
 ''''''''''''''''''''''
 
-``DataFrame`` objects have an instance method ``to_html`` which renders the
-contents of the ``DataFrame`` as an HTML table. The function arguments are as
-in the method ``to_string`` described above.
-
 .. note::
 
-   Not all of the possible options for ``DataFrame.to_html`` are shown here for
-   brevity's sake. See :func:`~pandas.core.frame.DataFrame.to_html` for the
-   full set of options.
+   DataFrame *and* Styler objects currently have a ``to_html`` method. We recommend
+   using the `Styler.to_html() <../reference/api/pandas.io.formats.style.Styler.to_html.rst>`__ method
+   over `DataFrame.to_html() <../reference/api/pandas.DataFrame.to_html.rst>`__ due to the former's greater flexibility with
+   conditional styling, and the latter's possible future deprecation.
 
-.. ipython:: python
-   :suppress:
+Review the documentation for `Styler.to_html <../reference/api/pandas.io.formats.style.Styler.to_html.rst>`__,
+which gives examples of conditional styling and explains the operation of its keyword
+arguments. The ``to_html`` methods render the contents of the ``DataFrame`` as an HTML table.
 
-   def write_html(df, filename, *args, **kwargs):
-       static = os.path.abspath(os.path.join("source", "_static"))
-       with open(os.path.join(static, filename + ".html"), "w") as f:
-           df.to_html(f, *args, **kwargs)
+For simple application the following pattern is sufficient:
 
 .. ipython:: python
 
    df = pd.DataFrame(np.random.randn(2, 2))
    df
-   print(df.to_html())  # raw html
-
-.. ipython:: python
-   :suppress:
-
-   write_html(df, "basic")
-
-HTML:
-
-.. raw:: html
-   :file: ../_static/basic.html
-
-The ``columns`` argument will limit the columns shown:
-
-.. ipython:: python
-
-   print(df.to_html(columns=[0]))
-
-.. ipython:: python
-   :suppress:
-
-   write_html(df, "columns", columns=[0])
-
-HTML:
-
-.. raw:: html
-   :file: ../_static/columns.html
-
-``float_format`` takes a Python callable to control the precision of floating
-point values:
-
-.. ipython:: python
-
-   print(df.to_html(float_format="{0:.10f}".format))
-
-.. ipython:: python
-   :suppress:
-
-   write_html(df, "float_format", float_format="{0:.10f}".format)
-
-HTML:
-
-.. raw:: html
-   :file: ../_static/float_format.html
-
-``bold_rows`` will make the row labels bold by default, but you can turn that
-off:
-
-.. ipython:: python
-
-   print(df.to_html(bold_rows=False))
-
-.. ipython:: python
-   :suppress:
+   print(df.style.to_html())  # raw html
 
-   write_html(df, "nobold", bold_rows=False)
-
-.. raw:: html
-   :file: ../_static/nobold.html
-
-The ``classes`` argument provides the ability to give the resulting HTML
-table CSS classes. Note that these classes are *appended* to the existing
-``'dataframe'`` class.
-
-.. ipython:: python
-
-   print(df.to_html(classes=["awesome_table_class", "even_more_awesome_class"]))
-
-The ``render_links`` argument provides the ability to add hyperlinks to cells
-that contain URLs.
-
-.. ipython:: python
-
-   url_df = pd.DataFrame(
-       {
-           "name": ["Python", "pandas"],
-           "url": ["https://www.python.org/", "https://pandas.pydata.org"],
-       }
-   )
-   print(url_df.to_html(render_links=True))
-
-.. ipython:: python
-   :suppress:
-
-   write_html(url_df, "render_links", render_links=True)
-
-HTML:
-
-.. raw:: html
-   :file: ../_static/render_links.html
-
-Finally, the ``escape`` argument allows you to control whether the
-"<", ">" and "&" characters escaped in the resulting HTML (by default it is
-``True``). So to get the HTML without escaped characters pass ``escape=False``
-
-.. ipython:: python
-
-   df = pd.DataFrame({"a": list("&<>"), "b": np.random.randn(3)})
-
-
-.. ipython:: python
-   :suppress:
-
-   write_html(df, "escape")
-   write_html(df, "noescape", escape=False)
-
-Escaped:
-
-.. ipython:: python
-
-   print(df.to_html())
-
-.. raw:: html
-   :file: ../_static/escape.html
-
-Not escaped:
+To format values before output, chain the `Styler.format <../reference/api/pandas.io.formats.style.Styler.format.rst>`__
+method.
 
 .. ipython:: python
 
-   print(df.to_html(escape=False))
-
-.. raw:: html
-   :file: ../_static/noescape.html
-
-.. note::
+   print(df.style.format("€ {}").to_html())
 
-   Some browsers may not show a difference in the rendering of the previous two
-   HTML tables.
+Some browsers or browser applications may process and add css class styling by default to alter the appearance
+of HTML tables, such as Jupyter Notebook and Google Colab.
 
 
 .. _io.html.gotchas:

doc/source/user_guide/scale.rst

@@ -275,6 +275,7 @@ column names and dtypes. That's because Dask hasn't actually read the data yet.
 Rather than executing immediately, doing operations build up a **task graph**.
 
 .. ipython:: python
+   :okwarning:
 
    ddf
    ddf["name"]
@@ -333,6 +334,7 @@ known automatically. In this case, since we created the parquet files manually,
 we need to supply the divisions manually.
 
 .. ipython:: python
+   :okwarning:
 
    N = 12
    starts = [f"20{i:>02d}-01-01" for i in range(N)]

doc/source/whatsnew/v1.4.0.rst

@@ -469,7 +469,7 @@ Other Deprecations
 - Deprecated :meth:`PeriodIndex.astype` to ``datetime64[ns]`` or ``DatetimeTZDtype``, use ``obj.to_timestamp(how).tz_localize(dtype.tz)`` instead (:issue:`44398`)
 - Deprecated passing ``skipna=None`` for :meth:`DataFrame.mad` and :meth:`Series.mad`, pass ``skipna=True`` instead (:issue:`44580`)
 - 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`)
+- A deprecation warning is now shown for both :meth:`DataFrame.to_html` and :meth:`DataFrame.to_latex` indicating the arguments signature may change and emulate more the arguments in :meth:`.Styler.to_html` and :meth:`.Styler.to_latex`, respectively, in future versions (:issue:`44411`, :issue:`44451`)
 -
 
 .. ---------------------------------------------------------------------------

pandas/core/frame.py

@@ -2898,8 +2898,18 @@ def to_html(
         %(returns)s
         See Also
         --------
+        Styler.to_html : Render a DataFrame to HTML with conditional formatting.
         to_string : Convert DataFrame to a string.
         """
+        msg = (
+            "In future versions `DataFrame.to_html` is expected to utilise the base "
+            "implementation of `Styler.to_html` for formatting and rendering. "
+            "The arguments signature may therefore change. It is recommended instead "
+            "to use `DataFrame.style.to_html` which also contains additional "
+            "functionality."
+        )
+        warnings.warn(msg, FutureWarning, stacklevel=find_stack_level())
+
         if justify is not None and justify not in fmt._VALID_JUSTIFY_PARAMETERS:
             raise ValueError("Invalid value for justify parameter")
 

pandas/tests/io/formats/test_format.py

@@ -3299,6 +3299,7 @@ def test_repr_html_ipython_config(ip):
 
 
 @pytest.mark.filterwarnings("ignore:In future versions `DataFrame.to_latex`")
+@pytest.mark.filterwarnings("ignore:In future versions `DataFrame.to_html`")
 @pytest.mark.parametrize("method", ["to_string", "to_html", "to_latex"])
 @pytest.mark.parametrize(
     "encoding, data",
@@ -3320,7 +3321,7 @@ def test_filepath_or_buffer_arg(
         ):
             getattr(df, method)(buf=filepath_or_buffer, encoding=encoding)
     elif encoding == "foo":
-        expected_warning = FutureWarning if method == "to_latex" else None
+        expected_warning = FutureWarning if method in ["to_latex", "to_html"] 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)

pandas/tests/io/formats/test_to_html.py

@@ -16,6 +16,8 @@
 
 import pandas.io.formats.format as fmt
 
+pytestmark = pytest.mark.filterwarnings("ignore::FutureWarning")
+
 lorem_ipsum = (
     "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod "
     "tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim "
@@ -872,3 +874,16 @@ def test_to_html_float_format_object_col(datapath):
     result = df.to_html(float_format=lambda x: f"{x:,.0f}")
     expected = expected_html(datapath, "gh40024_expected_output")
     assert result == expected
+
+
+def test_future_warning():
+    df = DataFrame([[1]])
+    msg = (
+        "In future versions `DataFrame.to_html` is expected to utilise the base "
+        "implementation of `Styler.to_html` for formatting and rendering. "
+        "The arguments signature may therefore change. It is recommended instead "
+        "to use `DataFrame.style.to_html` which also contains additional "
+        "functionality."
+    )
+    with tm.assert_produces_warning(FutureWarning, match=msg):
+        df.to_html()

pandas/tests/io/test_common.py

@@ -227,6 +227,7 @@ def test_read_non_existent(self, reader, module, error_class, fn_ext):
         ):
             reader(path)
 
+    @pytest.mark.filterwarnings("ignore:In future versions `DataFrame.to_html`")
     @pytest.mark.parametrize(
         "method, module, error_class, fn_ext",
         [
@@ -349,6 +350,7 @@ def test_read_fspath_all(self, reader, module, path, datapath):
             tm.assert_frame_equal(result, expected)
 
     @pytest.mark.filterwarnings("ignore:In future versions `DataFrame.to_latex`")
+    @pytest.mark.filterwarnings("ignore:In future versions `DataFrame.to_html`")
     @pytest.mark.parametrize(
         "writer_name, writer_kwargs, module",
         [

pandas/tests/io/test_html.py

@@ -118,6 +118,7 @@ def set_defaults(self, flavor, request):
         self.read_html = partial(read_html, flavor=flavor)
         yield
 
+    @pytest.mark.filterwarnings("ignore::FutureWarning")
     def test_to_html_compat(self):
         df = (
             tm.makeCustomDataframe(
@@ -877,6 +878,7 @@ def test_header_inferred_from_rows_with_only_th(self):
 
         tm.assert_frame_equal(result, expected)
 
+    @pytest.mark.filterwarnings("ignore::FutureWarning")
     def test_parse_dates_list(self):
         df = DataFrame({"date": date_range("1/1/2001", periods=10)})
         expected = df.to_html()
@@ -885,6 +887,7 @@ def test_parse_dates_list(self):
         res = self.read_html(expected, parse_dates=["date"], index_col=0)
         tm.assert_frame_equal(df, res[0])
 
+    @pytest.mark.filterwarnings("ignore::FutureWarning")
     def test_parse_dates_combine(self):
         raw_dates = Series(date_range("1/1/2001", periods=10))
         df = DataFrame(
@@ -1096,6 +1099,7 @@ def test_ignore_empty_rows_when_inferring_header(self):
 
         tm.assert_frame_equal(result, expected)
 
+    @pytest.mark.filterwarnings("ignore::FutureWarning")
     def test_multiple_header_rows(self):
         # Issue #13434
         expected_df = DataFrame(
@@ -1120,6 +1124,7 @@ def test_fallback_success(self, datapath):
         banklist_data = datapath("io", "data", "html", "banklist.html")
         self.read_html(banklist_data, match=".*Water.*", flavor=["lxml", "html5lib"])
 
+    @pytest.mark.filterwarnings("ignore::FutureWarning")
     def test_to_html_timestamp(self):
         rng = date_range("2000-01-01", periods=10)
         df = DataFrame(np.random.randn(10, 4), index=rng)