DEPR: Styler.render in favour of Styler.to_html (#42140)

Author: attack68

asv_bench/benchmarks/io/style.py

@@ -36,11 +36,11 @@ def peakmem_classes_render(self, cols, rows):
 
     def time_format_render(self, cols, rows):
         self._style_format()
-        self.st.render()
+        self.st._render_html(True, True)
 
     def peakmem_format_render(self, cols, rows):
         self._style_format()
-        self.st.render()
+        self.st._render_html(True, True)
 
     def _style_apply(self):
         def _apply_func(s):

doc/source/reference/style.rst

@@ -71,9 +71,8 @@ Style export and import
 .. autosummary::
    :toctree: api/
 
-   Styler.render
-   Styler.export
-   Styler.use
    Styler.to_html
-   Styler.to_excel
    Styler.to_latex
+   Styler.to_excel
+   Styler.export
+   Styler.use

doc/source/user_guide/style.ipynb

@@ -60,9 +60,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The above output looks very similar to the standard DataFrame HTML representation. But the HTML here has already attached some CSS classes to each cell, even if we haven't yet created any styles. We can view these by calling the  [.render()][render] method, which returns the raw HTML as string, which is useful for further processing or adding to a file - read on in [More about CSS and HTML](#More-About-CSS-and-HTML). Below we will show how we can use these to format the DataFrame to be more communicative. For example how we can build `s`:\n",
+    "The above output looks very similar to the standard DataFrame HTML representation. But the HTML here has already attached some CSS classes to each cell, even if we haven't yet created any styles. We can view these by calling the  [.to_html()][to_html] method, which returns the raw HTML as string, which is useful for further processing or adding to a file - read on in [More about CSS and HTML](#More-About-CSS-and-HTML). Below we will show how we can use these to format the DataFrame to be more communicative. For example how we can build `s`:\n",
     "\n",
-    "[render]: ../reference/api/pandas.io.formats.style.Styler.render.rst"
+    "[tohtml]: ../reference/api/pandas.io.formats.style.Styler.to_html.rst"
    ]
   },
   {
@@ -381,7 +381,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "out = s.set_table_attributes('class=\"my-table-cls\"').render()\n",
+    "out = s.set_table_attributes('class=\"my-table-cls\"').to_html()\n",
     "print(out[out.find('<table'):][:109])"
    ]
   },
@@ -1017,7 +1017,7 @@
     "      .set_table_styles([{'selector': 'td', 'props': props},\n",
     "                         {'selector': '.col1', 'props': 'color:green;'},\n",
     "                         {'selector': '.level0', 'props': 'color:blue;'}])\\\n",
-    "      .render()\\\n",
+    "      .to_html()\\\n",
     "      .replace('blank', '')\\\n",
     "      .replace('data', '')\\\n",
     "      .replace('level0', 'l0')\\\n",
@@ -1295,7 +1295,7 @@
     "        s.name=''\n",
     "        row += \"<td>{}</td>\".format(s.to_frame().style.hide_index().bar(align=align, \n",
     "                                                           color=['#d65f5f', '#5fba7d'], \n",
-    "                                                           width=100).render()) #testn['width']\n",
+    "                                                           width=100).to_html()) #testn['width']\n",
     "    row += '</tr>'\n",
     "    head += row\n",
     "    \n",
@@ -1616,9 +1616,9 @@
     "\n",
     "The structure of the `id` is `T_uuid_level<k>_row<m>_col<n>` where `level<k>` is used only on headings, and headings will only have either `row<m>` or `col<n>` whichever is needed. By default we've also prepended each row/column identifier with a UUID unique to each DataFrame so that the style from one doesn't collide with the styling from another within the same notebook or page. You can read more about the use of UUIDs in [Optimization](#Optimization).\n",
     "\n",
-    "We can see example of the HTML by calling the [.render()][render] method.\n",
+    "We can see example of the HTML by calling the [.to_html()][tohtml] method.\n",
     "\n",
-    "[render]: ../reference/api/pandas.io.formats.style.Styler.render.rst"
+    "[tohtml]: ../reference/api/pandas.io.formats.style.Styler.to_html.rst"
    ]
   },
   {
@@ -1627,7 +1627,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "print(pd.DataFrame([[1,2],[3,4]], index=['i1', 'i2'], columns=['c1', 'c2']).style.render())"
+    "print(pd.DataFrame([[1,2],[3,4]], index=['i1', 'i2'], columns=['c1', 'c2']).style.to_html())"
    ]
   },
   {
@@ -1854,7 +1854,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Our custom template accepts a `table_title` keyword. We can provide the value in the `.render` method."
+    "Our custom template accepts a `table_title` keyword. We can provide the value in the `.to_html` method."
    ]
   },
   {
@@ -1863,7 +1863,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "HTML(MyStyler(df3).render(table_title=\"Extending Example\"))"
+    "HTML(MyStyler(df3).to_html(table_title=\"Extending Example\"))"
    ]
   },
   {
@@ -1880,7 +1880,7 @@
    "outputs": [],
    "source": [
     "EasyStyler = Styler.from_custom_template(\"templates\", \"myhtml.tpl\")\n",
-    "HTML(EasyStyler(df3).render(table_title=\"Another Title\"))"
+    "HTML(EasyStyler(df3).to_html(table_title=\"Another Title\"))"
    ]
   },
   {
@@ -1990,7 +1990,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.6"
+   "version": "3.8.7"
   }
  },
  "nbformat": 4,

doc/source/whatsnew/v1.4.0.rst

@@ -208,7 +208,7 @@ Deprecations
 - Deprecated the 'kind' argument in :meth:`Index.get_slice_bound`, :meth:`Index.slice_indexer`, :meth:`Index.slice_locs`; in a future version passing 'kind' will raise (:issue:`42857`)
 - Deprecated dropping of nuisance columns in :class:`Rolling`, :class:`Expanding`, and :class:`EWM` aggregations (:issue:`42738`)
 - Deprecated :meth:`Index.reindex` with a non-unique index (:issue:`42568`)
--
+- Deprecated :meth:`.Styler.render` in favour of :meth:`.Styler.to_html` (:issue:`42140`)
 
 .. ---------------------------------------------------------------------------
 

pandas/io/formats/style.py

@@ -151,7 +151,7 @@ class Styler(StylerRenderer):
     be applied to the indicated cells.
 
     If using in the Jupyter notebook, Styler has defined a ``_repr_html_``
-    to automatically render itself. Otherwise call Styler.render to get
+    to automatically render itself. Otherwise call Styler.to_html to get
     the generated HTML.
 
     CSS classes are attached to the generated HTML
@@ -214,7 +214,7 @@ def _repr_html_(self) -> str:
         """
         Hooks into Jupyter notebook rich display system.
         """
-        return self.render()
+        return self.to_html()
 
     def render(
         self,
@@ -225,6 +225,8 @@ def render(
         """
         Render the ``Styler`` including all applied styles to HTML.
 
+        .. deprecated:: 1.4.0
+
         Parameters
         ----------
         sparse_index : bool, optional
@@ -248,11 +250,14 @@ def render(
 
         Notes
         -----
+        This method is deprecated in favour of ``Styler.to_html``.
+
         Styler objects have defined the ``_repr_html_`` method
-        which automatically calls ``self.render()`` when it's the
-        last item in a Notebook cell. When calling ``Styler.render()``
-        directly, wrap the result in ``IPython.display.HTML`` to view
-        the rendered HTML in the notebook.
+        which automatically calls ``self.to_html()`` when it's the
+        last item in a Notebook cell.
+
+        When calling ``Styler.render()`` directly, wrap the result in
+        ``IPython.display.HTML`` to view the rendered HTML in the notebook.
 
         Pandas uses the following keys in render. Arguments passed
         in ``**kwargs`` take precedence, so think carefully if you want
@@ -266,6 +271,11 @@ def render(
         * caption
         * table_attributes
         """
+        warnings.warn(
+            "this method is deprecated in favour of `Styler.to_html()`",
+            FutureWarning,
+            stacklevel=2,
+        )
         if sparse_index is None:
             sparse_index = get_option("styler.sparse.index")
         if sparse_columns is None:
@@ -336,7 +346,7 @@ def set_tooltips(
         >>> ttips = pd.DataFrame(
         ...    data=[["Min", ""], [np.nan, "Max"]], columns=df.columns, index=df.index
         ... )
-        >>> s = df.style.set_tooltips(ttips).render()
+        >>> s = df.style.set_tooltips(ttips).to_html()
 
         Optionally controlling the tooltip visual display
 
@@ -550,7 +560,7 @@ def to_latex(
         >>> df = pd.DataFrame([[1,2], [3,4]])
         >>> s = df.style.highlight_max(axis=None,
         ...                            props='background-color:red; font-weight:bold;')
-        >>> s.render()  # doctest: +SKIP
+        >>> s.to_html()  # doctest: +SKIP
 
         The equivalent using LaTeX only commands is the following:
 
@@ -831,6 +841,7 @@ def to_html(
         encoding: str | None = None,
         doctype_html: bool = False,
         exclude_styles: bool = False,
+        **kwargs,
     ):
         """
         Write Styler to a file, buffer or string in HTML-CSS format.
@@ -875,6 +886,10 @@ def to_html(
             Whether to include the ``<style>`` element and all associated element
             ``class`` and ``id`` identifiers, or solely the ``<table>`` element without
             styling identifiers.
+        **kwargs
+            Any additional keyword arguments are passed through to the jinj2
+            ``self.template.render`` process. This is useful when you need to provide
+            additional variables for a custom template.
 
         Returns
         -------
@@ -903,6 +918,7 @@ def to_html(
             exclude_styles=exclude_styles,
             encoding=encoding if encoding else "utf-8",
             doctype_html=doctype_html,
+            **kwargs,
         )
 
         return save_to_buffer(
@@ -961,7 +977,7 @@ def set_td_classes(self, classes: DataFrame) -> Styler:
         >>> df = pd.DataFrame([[1]])
         >>> css = pd.DataFrame([["other-class"]])
         >>> s = Styler(df, uuid="_", cell_ids=False).set_td_classes(css)
-        >>> s.hide_index().render()  # doctest: +SKIP
+        >>> s.hide_index().to_html()  # doctest: +SKIP
         '<style type="text/css"></style>'
         '<table id="T__">'
         '  <thead>'

pandas/io/formats/style_render.py

@@ -735,7 +735,7 @@ def format(
         >>> s = df.style.format(
         ...     '<a href="a.com/{0}">{0}</a>', escape="html", na_rep="NA"
         ...     )
-        >>> s.render()  # doctest: +SKIP
+        >>> s.to_html()  # doctest: +SKIP
         ...
         <td .. ><a href="a.com/&lt;div&gt;&lt;/div&gt;">&lt;div&gt;&lt;/div&gt;</a></td>
         <td .. ><a href="a.com/&#34;A&amp;B&#34;">&#34;A&amp;B&#34;</a></td>