WARN: Add FutureWarning to `DataFrame.to_html`
State: closed

This follows #44411 and has the same purpose.

xref https://github.com/pandas-dev/pandas/issues/41693

Labels:
name: IO HTML
description: read_html, to_html, Styler.apply, Styler.applymap
name: Deprecate
description: Functionality to remove in pandas

Comments:
this is getting stale, any further comments / suggestions?
@jorisvandenbossche ok here?
@attack68 thanks for the updates and adding more specific warnings, and sorry for the slow response. 

> Warnings are shown in 1.4.0 in preparation for signature changes in 2.0.0

Typically, if we deprecate keywords in favor of new ones, the new one is already added so that users have a direct alternative and can use the new keyword to not get the deprecation warning. 

Is there a reason we can't do that here? 
> Is there a reason we can't do that here?

Yeh I think so. Its a special situation where the implementation we want to transition to already exists via another object (which the user can immediately transition to if preferred), but where the treatment of each argument is a bit different, e.g:

To avoid the warnings the user could (and maybe should follow the warning) and switch to using ``df.style.format().to_html()`` instead of ``df.to_html()``
 
> Its a special situation where the implementation we want to transition to already exists via another object (which the user can immediately transition to if preferred), but where the treatment of each argument is a bit different, 

But so what's the plan in the future for those new keyword arguments? They will then be passed through to `Styler.to_html` which gets used under the hood in `DataFrame.to_html`? 
Is that something we could already do now if those new keywords get specified?
Something else: in general, I think we should also make a clear decision on the future of `DataFrame.to_html` now. Currently, the docs you added are quite vague indicating it might go away in the future. I don't think that's a very useful message to the user. 

If we think we will keep `DataFrame.to_html` as a light wrapper around `Styler.to_html`, IMO we don't need to be that vague in the docs.
> Is that something we could already do now if those new keywords get specified?

The goal is to remove the necessity for `DataFrameHTMLFormatter` and `DataFrameLaTexFormatter`, and parse the inputs to `DataFrame.to_html()` and `DataFrame.to_latex()` into a format which can utilise the `Styler` implementation to return the result.

As far as I am currently aware all the development is in place to make the transition as of now.  See #41648 as a complete example of this for `to_latex` and #43161 as an unfinished attempt for `to_html`.

These PRs were closed because the opinion was that a deprecation cycle was needed before making argument signature changes, which I do agree with.

As far as the 'vagueness' goes in the docs, which I agree is there, I am confident that this can be done and I am happy to implement it, but my uncertainty is based on the approval of the community..
> These PRs were closed because the opinion was that a deprecation cycle was needed before making argument signature changes, which I do agree with.

Yes, but doing the deprecation ànd already providing the new option can be done in the same release. If you specify one of the new keywords, we could make it use the new implementation. That should be both backwards compatible (all existing uses continue to use the old implementation, only when you change your code (eg to adjust for deprecation warnings), you might get the new implementation), and already make the future behaviour possible. 

> As far as the 'vagueness' goes in the docs, which I agree is there, I am confident that this can be done and I am happy to implement it, but my uncertainty is based on the approval of the community..

Yes, and so I know that's not a concrete comment for you to solve in the code, but I still think we (as pandas community) should first decide on this. 
My personal opinion: I would leave `DataFrame.to_html` just as it is: 1) many use cases will not use one of the more advanced keywords, and for those there is not much reason to ask them to change their code, 2) we have a bunch of `to_..` methods on the DataFrame, having `to_html` as well is good for both consistency and discoverability (and of course we still refer to `style.to_html()` if you want more advanced control). 
> > As far as the 'vagueness' goes in the docs, which I agree is there, I am confident that this can be done and I am happy to implement it, but my uncertainty is based on the approval of the community..
> 
> Yes, and so I know that's not a concrete comment for you to solve in the code, but I still think we (as pandas community) should first decide on this.

Is there an issue that already has some discussion on this topic?
 > Yes, but doing the deprecation ànd already providing the new option can be done in the same release. If you specify one of the new keywords, we could make it use the new implementation. That should be both backwards compatible (all existing uses continue to use the old implementation, only when you change your code (eg to adjust for deprecation warnings), you might get the new implementation), and already make the future behaviour possible.

I gave this a go in #45090. That might be a better route..

moving to 1.5
will close this for now in favour of #45090. Can revive later if needed