API: Styler copy, export, use, clear methods purpose and implementation

[attack68]

PR Tracking

• copy mechanics (CLN: simplify Styler copy mechanics and tests #42187)
• clear mechanics (CLN: simplify Styler clear mechanics and tests #42271)
• export mechanics (REF: Styler.export #43318)
• use mechanics (REF: Styler.export #43318)

Post

The 4 methods attached to Styler have weakly defined purposes and implementation. Some recent PRs have sought to address this
[#40664 and #39975] but none go all the way.

So lets define a purpose:

• export and use are designed to work together to transfer all non-data dependent styles from one Styler to another.
• copy aims to recreate a new Styler object which contains the same data and styles as the original.
• clear only operates on a single instance and seeks to set it to a default state.

How does this work in practice with the different Styler attributes:

Non-Ambiguous Attributes

Fully Data Dependent: should be copied but not exported.

• Tooltips
• set_td_classes and cell_context
• hidden_columns, hidden_rows
• format (the format method maps formatting functions to the data internally)

Non-Data Dependent: should be copied and exported

• hide_index_, hide_columns_:
• hidden_header (future development)
• table_attributes

Ambiguous Attributes

• apply and applymap and _todo: should be copied and exported. The user must deal with data dependency, since they have optionally introduced it.

The apply and applymap methods operate by default in a non-data dependent way and optionally become data dependent when the subset argument is used or if the functions given are somehow data dependent themselves.

• table_styles: should be copied and exported. The user must deal with data dependency.

Table styles provide a generic non-data dependent way of adding styles. It can also be data dependent when the CSS selectors target specific rows or colums that might depend on the data. For consistency we include in export and make the user deal with data dependency. (Since Tooltips add table styles dynamically at render time this will not be exported.)

• uuid: is not copied copied and not exported

The uuid is an attribute designed specifically to avoid CSS clashes. It is preferable to have 2 objects with different uuids, and potentially erroneous for them to have the same, therefore we avoid copying or exporting the uuid.

edit 14-august-2021: In order to use to_html with args without impacting the styler we must be able to fully copy a styler including uuid: see #43034. Therefore this is copied.

• caption: is copied and not exported.

A caption is usually data-dependent, although not necessarily hence not exported.

Clearing

Some attributes can be provided at class instantiation, so "clearing" a Styler could be seen as reseting to these values. In order to do this, the instantiation variables need to be saved, which is unnecessary overhead. Another interpretation is that the Styler instantiation is rarely called specifically with args, and these can be seen as syntactic sugar for, instead calling a default Styler and then immediately applying the relevant modifiers.
Weighing these arguments it seems best to clear a Styler back to its default instantiation without any applied arguments.
The most thorough and future proof clearing method might be to re-instantiate a new object, with default inputs:

def clear(self):
    return Styler(self.data)