API: Add Styler.to_html, for saving output to HTML file (#40312)

Author: attack68

doc/source/whatsnew/v1.3.0.rst

@@ -142,7 +142,7 @@ properly format HTML and eliminate some inconsistencies (:issue:`39942` :issue:`
 One also has greater control of the display through separate sparsification of the index or columns, using the new 'styler' options context (:issue:`41142`).
 
 We have added an extension to allow LaTeX styling as an alternative to CSS styling and a method :meth:`.Styler.to_latex`
-which renders the necessary LaTeX format including built-up styles.
+which renders the necessary LaTeX format including built-up styles. An additional file io function :meth:`Styler.to_html` has been added for convenience (:issue:`40312`).
 
 Documentation has also seen major revisions in light of new features (:issue:`39720` :issue:`39317` :issue:`40493`)
 

pandas/io/formats/style.py

@@ -739,6 +739,74 @@ def to_latex(
 
         return save_to_buffer(latex, buf=buf, encoding=encoding)
 
+    def to_html(
+        self,
+        buf: FilePathOrBuffer[str] | None = None,
+        *,
+        table_uuid: str | None = None,
+        table_attributes: str | None = None,
+        encoding: str | None = None,
+        doctype_html: bool = False,
+        exclude_styles: bool = False,
+    ):
+        """
+        Write Styler to a file, buffer or string in HTML-CSS format.
+
+        .. versionadded:: 1.3.0
+
+        Parameters
+        ----------
+        buf : str, Path, or StringIO-like, optional, default None
+            Buffer to write to. If ``None``, the output is returned as a string.
+        table_uuid: str, optional
+            Id attribute assigned to the <table> HTML element in the format:
+
+            ``<table id="T_<table_uuid>" ..>``
+
+            If not given uses Styler's initially assigned value.
+        table_attributes: str, optional
+            Attributes to assign within the `<table>` HTML element in the format:
+
+            ``<table .. <table_attributes> >``
+
+            If not given defaults to Styler's preexisting value.
+        encoding : str, optional
+            Character encoding setting for file output, and HTML meta tags,
+            defaults to "utf-8" if None.
+        doctype_html : bool, default False
+            Whether to output a fully structured HTML file including all
+            HTML elements, or just the core ``<style>`` and ``<table>`` elements.
+        exclude_styles : bool, default False
+            Whether to include the ``<style>`` element and all associated element
+            ``class`` and ``id`` identifiers, or solely the ``<table>`` element without
+            styling identifiers.
+
+        Returns
+        -------
+        str or None
+            If `buf` is None, returns the result as a string. Otherwise returns `None`.
+
+        See Also
+        --------
+        DataFrame.to_html: Write a DataFrame to a file, buffer or string in HTML format.
+        """
+        if table_uuid:
+            self.set_uuid(table_uuid)
+
+        if table_attributes:
+            self.set_table_attributes(table_attributes)
+
+        # Build HTML string..
+        html = self.render(
+            exclude_styles=exclude_styles,
+            encoding=encoding if encoding else "utf-8",
+            doctype_html=doctype_html,
+        )
+
+        return save_to_buffer(
+            html, buf=buf, encoding=(encoding if buf is not None else None)
+        )
+
     def set_td_classes(self, classes: DataFrame) -> Styler:
         """
         Set the DataFrame of strings added to the ``class`` attribute of ``<td>``

pandas/io/formats/templates/html.tpl

@@ -1,70 +1,16 @@
-{# Update the template_structure.html document too #}
-{%- block before_style -%}{%- endblock before_style -%}
-{% block style %}
-<style type="text/css">
-{% block table_styles %}
-{% for s in table_styles %}
-#T_{{uuid}} {{s.selector}} {
-{% for p,val in s.props %}
-  {{p}}: {{val}};
-{% endfor %}
-}
-{% endfor %}
-{% endblock table_styles %}
-{% block before_cellstyle %}{% endblock before_cellstyle %}
-{% block cellstyle %}
-{% for s in cellstyle %}
-{% for selector in s.selectors %}{% if not loop.first %}, {% endif %}#T_{{uuid}}{{selector}}{% endfor %} {
-{% for p,val in s.props %}
-  {{p}}: {{val}};
-{% endfor %}
-}
-{% endfor %}
-{% endblock cellstyle %}
-</style>
-{% endblock style %}
-{% block before_table %}{% endblock before_table %}
-{% block table %}
-<table id="T_{{uuid}}"{% if table_attributes %} {{table_attributes}}{% endif %}>
-{% block caption %}
-{% if caption %}
-  <caption>{{caption}}</caption>
+{# Update the template_structure.html documentation too #}
+{% if doctype_html %}
+<!DOCTYPE html>
+<html>
+<head>
+<meta charset="{{encoding}}">
+{% if not exclude_styles %}{% include "html_style.tpl" %}{% endif %}
+</head>
+<body>
+{% include "html_table.tpl" %}
+</body>
+</html>
+{% elif not doctype_html %}
+{% if not exclude_styles %}{% include "html_style.tpl" %}{% endif %}
+{% include "html_table.tpl" %}
 {% endif %}
-{% endblock caption %}
-{% block thead %}
-  <thead>
-{% block before_head_rows %}{% endblock %}
-{% for r in head %}
-{% block head_tr scoped %}
-    <tr>
-{% for c in r %}
-{% if c.is_visible != False %}
-      <{{c.type}} class="{{c.class}}" {{c.attributes}}>{{c.value}}</{{c.type}}>
-{% endif %}
-{% endfor %}
-    </tr>
-{% endblock head_tr %}
-{% endfor %}
-{% block after_head_rows %}{% endblock %}
-  </thead>
-{% endblock thead %}
-{% block tbody %}
-  <tbody>
-{% block before_rows %}{% endblock before_rows %}
-{% for r in body %}
-{% block tr scoped %}
-    <tr>
-{% for c in r %}
-{% if c.is_visible != False %}
-      <{{c.type}} {% if c.id is defined -%} id="T_{{uuid}}{{c.id}}" {%- endif %} class="{{c.class}}" {{c.attributes}}>{{c.display_value}}</{{c.type}}>
-{% endif %}
-{% endfor %}
-    </tr>
-{% endblock tr %}
-{% endfor %}
-{% block after_rows %}{% endblock after_rows %}
-  </tbody>
-{% endblock tbody %}
-</table>
-{% endblock table %}
-{% block after_table %}{% endblock after_table %}

pandas/io/formats/templates/html_style.tpl

@@ -0,0 +1,24 @@
+{%- block before_style -%}{%- endblock before_style -%}
+{% block style %}
+<style type="text/css">
+{% block table_styles %}
+{% for s in table_styles %}
+#T_{{uuid}} {{s.selector}} {
+{% for p,val in s.props %}
+  {{p}}: {{val}};
+{% endfor %}
+}
+{% endfor %}
+{% endblock table_styles %}
+{% block before_cellstyle %}{% endblock before_cellstyle %}
+{% block cellstyle %}
+{% for s in cellstyle %}
+{% for selector in s.selectors %}{% if not loop.first %}, {% endif %}#T_{{uuid}}{{selector}}{% endfor %} {
+{% for p,val in s.props %}
+  {{p}}: {{val}};
+{% endfor %}
+}
+{% endfor %}
+{% endblock cellstyle %}
+</style>
+{% endblock style %}

pandas/io/formats/templates/html_table.tpl

@@ -0,0 +1,61 @@
+{% block before_table %}{% endblock before_table %}
+{% block table %}
+{% if exclude_styles %}
+<table>
+{% else %}
+<table id="T_{{uuid}}"{% if table_attributes %} {{table_attributes}}{% endif %}>
+{% endif %}
+{% block caption %}
+{% if caption %}
+  <caption>{{caption}}</caption>
+{% endif %}
+{% endblock caption %}
+{% block thead %}
+  <thead>
+{% block before_head_rows %}{% endblock %}
+{% for r in head %}
+{% block head_tr scoped %}
+    <tr>
+{% if exclude_styles %}
+{% for c in r %}
+{% if c.is_visible != False %}
+      <{{c.type}} {{c.attributes}}>{{c.value}}</{{c.type}}>
+{% endif %}
+{% endfor %}
+{% else %}
+{% for c in r %}
+{% if c.is_visible != False %}
+      <{{c.type}} class="{{c.class}}" {{c.attributes}}>{{c.value}}</{{c.type}}>
+{% endif %}
+{% endfor %}
+{% endif %}
+    </tr>
+{% endblock head_tr %}
+{% endfor %}
+{% block after_head_rows %}{% endblock %}
+  </thead>
+{% endblock thead %}
+{% block tbody %}
+  <tbody>
+{% block before_rows %}{% endblock before_rows %}
+{% for r in body %}
+{% block tr scoped %}
+    <tr>
+{% if exclude_styles %}
+{% for c in r %}{% if c.is_visible != False %}
+      <{{c.type}} {{c.attributes}}>{{c.display_value}}</{{c.type}}>
+{% endif %}{% endfor %}
+{% else %}
+{% for c in r %}{% if c.is_visible != False %}
+      <{{c.type}} {% if c.id is defined -%} id="T_{{uuid}}{{c.id}}" {%- endif %} class="{{c.class}}" {{c.attributes}}>{{c.display_value}}</{{c.type}}>
+{% endif %}{% endfor %}
+{% endif %}
+    </tr>
+{% endblock tr %}
+{% endfor %}
+{% block after_rows %}{% endblock after_rows %}
+  </tbody>
+{% endblock tbody %}
+</table>
+{% endblock table %}
+{% block after_table %}{% endblock after_table %}