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

docs/_quarto.yml

@@ -214,11 +214,12 @@ 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 `*_raw_html()` methods.
       contents:
         - GT.save
         - GT.show
         - GT.as_raw_html
+        - GT.write_raw_html
         - GT.as_latex
     - title: Pipeline
       desc: >

great_tables/_export.py

@@ -559,3 +559,42 @@ def _dump_debug_screenshot(driver, path):
         "document.getElementsByTagName('table')[0].style.border = '3px solid green'; "
     )
     driver.save_screenshot(path)
+
+
+def write_raw_html(
+    gt: GT,
+    filename: str | Path,
+    encoding: str = "utf-8",
+    newline: str | None = None,
+    make_page: bool = False,
+    all_important: bool = False,
+) -> 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.
+    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
+    -------
+    None
+        An HTML file is written to the specified path and the method returns `None`.
+    """
+    import os
+
+    html_content = as_raw_html(gt, make_page=make_page, all_important=all_important)
+
+    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

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

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
@@ -121,6 +122,24 @@ def test_create_temp_file_server():
         thread.join()
 
 
+def test_write_raw_html_raises(gt_tbl):
+    with pytest.raises(TypeError):
+        gt_tbl.write_raw_html()  # `filename=` must be specified
+
+
+def test_write_raw_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_raw_html(p_file)
+        assert p_file.exists()
+
+        # Pass the filename as a string
+        s_file = str(Path(tmp_dir, "table2.html"))
+        gt_tbl.write_raw_html(s_file)
+        assert Path(s_file).exists()
+
+
 def test_snap_as_latex(snapshot):
     gt_tbl = (
         GT(