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

[jrycw]

Hello team,

I've noticed that some users expect an easier way to interact with our tables. While GT.as_raw_html() is great, it doesn’t fully meet those expectations. To address this, I’d like to propose adding GT.write_html() as a helper function, simplifying the process of writing the table’s HTML directly to a file without needing to use open().

I believe this is a useful addition, and if necessary, we could even rename it to GT._write_html() for unofficial use.

[codecov[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 90.68%. Comparing base (0dad744) to head (fae9c46). Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #485      +/-   ##
==========================================
+ Coverage   90.67%   90.68%   +0.01%     
==========================================
  Files          46       46              
  Lines        5381     5388       +7     
==========================================
+ Hits         4879     4886       +7     
  Misses        502      502              

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

[jrycw]

I've found that utilizing the parameters of GT.as_raw_html() might be a better approach. I suggest we keep the make_page and all_important parameters undocumented, similar to how it's done in GT.as_raw_html().

[machow]

Thanks for this @jrycw -- @rich-iannone and I are pairing on this right now, and thinking about the use of both .as_*() and .write_*() in the Great Tables API.

We noticed that polars .write_*() methods will return a string, if not filename is specified. WDYT of that approach. So in that case, we would deprecate the as_*() methods in favor of write_*() methods.

Basically, it seems like there are 3 possible approaches:

• polars: .write_*() methods return a string when no filename given
• two kinds of methods: each render target has a .as_*() and .write_*() method.
• polars approach, but with .as_*(): use .as_*() instead of .write_*()

Would love to get your input!

[jrycw]

Hello team,

I’m inclined to go with the first option as the higher-level abstraction while retaining .as_*() for internal use.

Here’s my draft implementation below.

[jrycw]

To issue a deprecation message to users, we could take a similar approach to what Polars uses. We might consider decorating as_raw_html() in the GT object, like this:

class GT(GTData):
    ...

    as_raw_html = deprecate_function("Use `GT.write_html()` instead.", version="0.15.0")(as_raw_html) 
    write_html = write_html

This method avoids directly decorating as_raw_html(), which could trigger the message unintentionally when using write_html(). Once we’re ready for full deprecation, we can simply remove the line: as_raw_html = ....

[rich-iannone]

With some discussion with @machow we decided on using this option (from the list of three further above)

• two kinds of methods: each render target has a .as_*() and .write_*() method.

The reasoning is that we don't have a lot of conversion methods so we don't have to be too economical on the number of export methods. Plus having output type stability would make more clear what the intended effect of the method is.

So the exported methods needed are:

• as_raw_html()
• write_raw_html()
• as_latex()
• write_latex()

The last one write_latex() could be done here or in another PR (up to you).

[jrycw]

I would suggest moving write_latex() to a separate PR. Could the team review whether this PR meets the expectations for write_raw_html()? Thanks!

[jrycw]

I suspect the doc build failure might be related to the change in Polars (pl.DataFrame.deserialize).

[rich-iannone]

I suspect the doc build failure might be related to the change in Polars (pl.DataFrame.deserialize).

We can fix that in a separate PR, so don't worry about that one right here.

[machow]

@rich-iannone feel free to merge after re-reviewing

[rich-iannone]

This looks great now. Will merge.