ENH: Styler can add tooltips directly from a DataFrame of strings

Author: attack68

pandas/io/formats/style.py

@@ -18,7 +18,7 @@
     Tuple,
     Union,
 )
-from uuid import uuid1
+from uuid import uuid4
 
 import numpy as np
 
@@ -159,7 +159,7 @@ def __init__(
         self.index = data.index
         self.columns = data.columns
 
-        self.uuid = uuid
+        self.uuid = uuid or (uuid4().hex[:6] + "_")
         self.table_styles = table_styles
         self.caption = caption
         if precision is None:
@@ -171,6 +171,11 @@ def __init__(
         self.cell_ids = cell_ids
         self.na_rep = na_rep
 
+        self.tooltip_styles = None  # VERSION ADDED 1.X
+        self.tooltip_class = None
+        self.tooltip_class_styles = None
+        self.set_tooltip_class(name='pd-t', properties=None)
+
         # display_funcs maps (row, col) -> formatting function
 
         def default_display_func(x):
@@ -246,7 +251,7 @@ def _translate(self):
         precision = self.precision
         hidden_index = self.hidden_index
         hidden_columns = self.hidden_columns
-        uuid = self.uuid or str(uuid1()).replace("-", "_")
+        uuid = self.uuid
         ROW_HEADING_CLASS = "row_heading"
         COL_HEADING_CLASS = "col_heading"
         INDEX_NAME_CLASS = "index_name"
@@ -802,6 +807,124 @@ def where(
             lambda val: value if cond(val) else other, subset=subset, **kwargs
         )
 
+    def set_tooltips(self, ttips: DataFrame):
+        """
+        Add string based tooltips that will appear in the `Styler` HTML result.
+
+        Parameters
+        ----------
+        ttips : DataFrame
+            DataFrame containing strings that will be translated to tooltips. Empty
+            strings, None, or NaN values will be ignored. DataFrame must have
+            identical rows and columns to the underlying `Styler` data.
+
+        Returns
+        -------
+        self : Styler
+
+        Notes
+        -----
+        Tooltips are created by adding `<span class="pd-t"></span>` to each data cell
+        and then manipulating the table level CSS to attach pseudo hover and pseudo after
+        selectors to produce the required the results. For styling control
+        see `:meth:Styler.set_tooltips_class`.
+        Tooltips are not designed to be efficient, and can add large amounts of additional
+        HTML for larger tables, since they also require that `cell_ids` is forced to `True`.
+
+        :param ttips:
+        :return:
+        """
+        if not (self.columns.equals(ttips.columns) and self.index.equals(ttips.index)):
+            raise AttributeError('Tooltips DataFrame must have identical column and index labelling to underlying.')
+
+        self.cell_ids = True  # tooltips only work with individual cell_ids
+        self.tooltip_styles = []
+        for i, rn in enumerate(ttips.index):
+            for j, cn in enumerate(ttips.columns):
+                if ttips.iloc[i, j] in [np.nan, '', None]:
+                    continue
+                else:
+                    # add pseudo-class and pseudo-elements to css to create tips
+                    self.tooltip_styles.extend([
+                        {'selector': '#T_' + self.uuid + 'row' + str(i) + '_col' + str(j) + f':hover .{self.tooltip_class}',
+                         'props': [('visibility', 'visible')]},
+                        {'selector': '#T_' + self.uuid + 'row' + str(i) + '_col' + str(j) + f' .{self.tooltip_class}::after',
+                         'props': [('content', f'"{str(ttips.iloc[i, j])}"')]}])
+
+        return self
+
+    def set_tooltip_class(self, name='pd-t', properties=None):
+        """
+        Method to set the name and properties of the class for creating tooltips on hover.
+
+        Parameters
+        ----------
+        name : str, default 'pd-t'
+            Name of the tooltip class used in CSS, should conform to HTML standards.
+        properties : list-like, default None
+            List of (attr, value) tuples; see example. If `None` will use defaults.
+
+        Returns
+        -------
+        self : Styler
+
+        Notes
+        -----
+        Default properties for the tooltip class are as follows:
+
+        - visibility: hidden
+        - position: absolute
+        - z-index: 1
+        - background-color: black
+        - color: white
+        - transform: translate(-20px, -20px)
+
+        Examples
+        --------
+        >>> df = pd.DataFrame(np.random.randn(10, 4))
+        >>> df.style.set_tooltip_class(name='tt-add', properties=[
+        ...     ('visibility', 'hidden'),
+        ...     ('position', 'absolute'),
+        ...     ('z-index', 1)])
+        """
+        if properties is None:
+            properties= [  # set default
+                ('visibility', 'hidden'),
+                ('position', 'absolute'),
+                ('z-index', 1),
+                ('background-color', 'black'),
+                ('color', 'white'),
+                ('transform', 'translate(-20px, -20px)')
+            ]
+        self.tooltip_class = name
+
+        self.tooltip_class_styles = [
+            {'selector': f'.{self.tooltip_class}',
+             'props': properties
+             }
+        ]
+        return self
+
+    def _render_tooltips(self, d):
+        """
+        Mutate the render dictionary to allow for tooltips:
+
+        - Add `<span>` HTML element to each data cells `display_value`. Ignores headers.
+        - Add table level CSS styles to control pseudo classes.
+
+        Parameters
+        ----------
+        d : dict
+            The dictionary prior to rendering
+        """
+        if self.tooltip_styles:
+            for row in d['body']:
+                for item in row:
+                    if item['type'] == 'td':
+                        item['display_value'] = str(item['display_value']) + f'<span class="{self.tooltip_class}"></span>'
+            d['table_styles'].extend(self.tooltip_class_styles)
+            d['table_styles'].extend(self.tooltip_styles)
+
     def set_precision(self, precision: int) -> "Styler":
         """
         Set the precision used to render.

pandas/tests/io/formats/test_style.py

@@ -1688,6 +1688,18 @@ def test_no_cell_ids(self):
         s = Styler(df, uuid="_", cell_ids=False).render()
         assert s.find('<td  class="data row0 col0" >') != -1
 
+    def test_tooltip_render(self):
+        # GH XXXXX
+        df = pd.DataFrame(data=[[0, 1], [2, 3]])
+        ttips = pd.DataFrame(data=[['Min', ''], [np.nan, 'Max']], columns=df.columns, index=df.index)
+        s = Styler(df, uuid="_").set_tooltips(ttips)
+        # test tooltip table level class
+        assert "#T__ .pd-t {" in s.render()
+        # test 'min' tooltip added
+        assert '#T__ #T__row0_col0:hover .pd-t {\n          visibility: visible;\n    }    #T__ #T__row0_col0 .pd-t::after {\n          content: "Min";\n    }' in s.render()
+        # test 'max' tooltip added
+        assert '#T__ #T__row1_col1:hover .pd-t {\n          visibility: visible;\n    }    #T__ #T__row1_col1 .pd-t::after {\n          content: "Max";\n    }' in s.render()
+
 
 @td.skip_if_no_mpl
 class TestStylerMatplotlibDep: