Add GT.write_html() as a helper function for easier HTML output

docs/_quarto.yml

@@ -209,11 +209,11 @@ quartodoc:
       desc: >
         There may come a day when you need to export a table to some specific format. A great method
         for that is `save()`, which allows us to save the table as a standalone image file. You can
-        also get the table code as an HTML fragment with the `as_raw_html()` method.
+        also get the table code as an HTML fragment with the `write_html()` method.
       contents:
         - GT.save
         - GT.show
-        - GT.as_raw_html
+        - GT.write_html
         - GT.as_latex
     - title: Value formatting functions
       desc: >

great_tables/_export.py

@@ -539,3 +539,47 @@ def _dump_debug_screenshot(driver, path):
         "document.getElementsByTagName('table')[0].style.border = '3px solid green'; "
     )
     driver.save_screenshot(path)
+
+
+def write_html(
+    gt: GT,
+    filename: str | Path | None = None,
+    encoding: str = "utf-8",
+    newline: str | None = None,
+    make_page: bool = False,
+    all_important: bool = False,
+) -> str | None:
+    """
+    Write the table to an HTML file.
+
+    This helper function saves the output of `GT.as_raw_html()` to an HTML file specified by the
+    user.
+
+    Parameters
+    ----------
+    gt
+        A GT object.
+    filename
+        The name of the file to save the HTML. Can be a string or a `pathlib.Path` object.
+        If set to `None` (default), the output is returned as a string instead.
+    encoding
+        The encoding used when writing the file. Defaults to 'utf-8'.
+    newline
+        The newline character to use when writing the file. Defaults to `os.linesep`.
+    Returns
+    -------
+    str | None
+        If `filename` is `None` (default), returns the HTML output as a string. Otherwise, writes
+        the HTML to the specified file path and returns `None`.
+    """
+    html_content = as_raw_html(gt, make_page=make_page, all_important=all_important)
+
+    if filename is None:
+        return html_content
+
+    import os
+
+    newline = newline if newline is not None else os.linesep
+
+    with open(filename, "w", encoding=encoding, newline=newline) as f:
+        f.write(html_content)

great_tables/gt.py

@@ -10,7 +10,8 @@
 from great_tables._body import body_reassemble
 from great_tables._boxhead import cols_align, cols_label
 from great_tables._data_color import data_color
-from great_tables._export import as_raw_html, as_latex, save, show
+from great_tables._export import as_raw_html, as_latex, save, show, write_html
+
 from great_tables._formats import (
     fmt,
     fmt_bytes,
@@ -272,6 +273,7 @@ def __init__(
     save = save
     show = show
     as_raw_html = as_raw_html
+    write_html = write_html
     as_latex = as_latex
 
     # -----

tests/test_export.py

@@ -6,7 +6,8 @@
 
 from great_tables import GT, exibble, md
 from great_tables.data import gtcars
-from great_tables._export import _infer_render_target, _create_temp_file_server
+from great_tables._export import as_raw_html, _infer_render_target, _create_temp_file_server
+
 from pathlib import Path
 
 from IPython.terminal.interactiveshell import TerminalInteractiveShell, InteractiveShell
@@ -99,6 +100,23 @@ def test_create_temp_file_server():
         thread.join()
 
 
+def test_write_html_default(gt_tbl):
+    assert as_raw_html(gt_tbl) == gt_tbl.write_html()
+
+
+def test_write_html(gt_tbl):
+    with tempfile.TemporaryDirectory() as tmp_dir:
+        # pass the filename as a pathlib.Path() object
+        p_file = Path(tmp_dir, "table1.html")
+        gt_tbl.write_html(p_file)
+        assert p_file.exists()
+
+        # Pass the filename as a string
+        s_file = str(Path(tmp_dir, "table2.html"))
+        gt_tbl.write_html(s_file)
+        assert Path(s_file).exists()
+
+
 def test_snap_as_latex(snapshot):
 
     gt_tbl = (