From 76aca6cdeb567d9aad561940679053b50edc7b53 Mon Sep 17 00:00:00 2001
From: Jerry Wu <jerry@ycwu.space>
Date: Thu, 16 Jan 2025 03:15:59 +0800
Subject: [PATCH] Add `GT.write_raw_html()` as a helper function for easier
 HTML output (#485)

* Add `GT.write_html()` function

* Add tests for `GT.write_html()` function

* update _quarto.yml to expose `GT.write_html()`

* Remove usage of the `os` module in tests for `GT.write_html()`

* Leverage the parameters of `GT.as_raw_html()`

* Update `.write_html()` to return a string if no filename is specified

* Update _quarto.yml

* Import `write_html()` to gt.py

* Fix pre-commit

* Update docstrings for `write_html()`

* Rename `write_html()` to `write_raw_html()`

* Apply suggestions from code review

Co-authored-by: Richard Iannone <riannone@me.com>

* Respect type stability in `write_raw_html`

* Tweak docstring entry on Return value

---------

Co-authored-by: Richard Iannone <riannone@me.com>
---
 docs/_quarto.yml        |  3 ++-
 great_tables/_export.py | 39 +++++++++++++++++++++++++++++++++++++++
 great_tables/gt.py      |  3 ++-
 tests/test_export.py    | 21 ++++++++++++++++++++-
 4 files changed, 63 insertions(+), 3 deletions(-)

diff --git a/docs/_quarto.yml b/docs/_quarto.yml
index d8b52d3d7..8e5f8d1fd 100644
--- a/docs/_quarto.yml
+++ b/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: >
diff --git a/great_tables/_export.py b/great_tables/_export.py
index e5f0183e3..11e89a3c8 100644
--- a/great_tables/_export.py
+++ b/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)
diff --git a/great_tables/gt.py b/great_tables/gt.py
index af917597c..ed1b84a19 100644
--- a/great_tables/gt.py
+++ b/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
diff --git a/tests/test_export.py b/tests/test_export.py
index df1e9b227..4a4a5afd5 100644
--- a/tests/test_export.py
+++ b/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(