ENH: Styler tooltips feature

doc/source/user_guide/style.ipynb

@@ -1241,4 +1241,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 1
-}
+}

doc/source/whatsnew/v1.2.0.rst

@@ -104,6 +104,7 @@ Other enhancements
 - :meth:`DataFrame.applymap` now supports ``na_action`` (:issue:`23803`)
 - :class:`Index` with object dtype supports division and multiplication (:issue:`34160`)
 - :meth:`DataFrame.explode` and :meth:`Series.explode` now support exploding of sets (:issue:`35614`)
+- `Styler` now has the ability to add tooltips to styled dataframes from strings (:issue:`35643`)
 -
 
 .. _whatsnew_120.api_breaking.python:

pandas/io/formats/style.py

@@ -159,7 +159,7 @@ def __init__(
         self.index = data.index
         self.columns = data.columns
 
-        self.uuid = uuid
+        self.uuid = uuid or str(uuid1()).replace("-", "_")
         self.table_styles = table_styles
         self.caption = caption
         if precision is None:
@@ -171,6 +171,8 @@ def __init__(
         self.cell_ids = cell_ids
         self.na_rep = na_rep
 
+        self.tooltips = _Tooltips()
+
         # display_funcs maps (row, col) -> formatting function
 
         def default_display_func(x):
@@ -192,6 +194,91 @@ def _repr_html_(self) -> str:
         """
         return self.render()
 
+    def set_tooltips(self, ttips: DataFrame) -> "Styler":
+        """
+        Add string based tooltips that will appear in the `Styler` HTML result. These
+        tooltips are applicable only to`<td>` elements.
+
+        Parameters
+        ----------
+        ttips : DataFrame
+            DataFrame containing strings that will be translated to tooltips, mapped
+            by identical column and index values that must exist on the underlying
+            `Styler` data. None, NaN values, and empty strings will be ignored and
+            not affect the rendered HTML.
+
+        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`.
+
+        Examples
+        --------
+        >>> 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).render()
+        """
+        if not self.cell_ids:
+            # tooltips not optimised for individual cell check.
+            raise NotImplementedError(
+                "Tooltips can only render with 'cell_ids' is True."
+            )
+        self.tooltips.tt_data = ttips
+        return self
+
+    def set_tooltips_class(
+        self,
+        name: Optional[str] = None,
+        properties: Optional[List[Tuple[str, Union[str, int, float]]]] = None,
+    ) -> "Styler":
+        """
+        Manually configure the name and/or properties of the class for
+        creating tooltips on hover.
+
+        Parameters
+        ----------
+        name : str, default None
+            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.
+
+        Returns
+        -------
+        self : Styler
+
+        Notes
+        -----
+        If arguments are `None` will not make any changes to the underlying ``Tooltips``
+        existing values.
+
+        The property ('visibility', 'hidden') should always be included in any manual
+        properties specification, to allow for HTML on hover functionality.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame(np.random.randn(10, 4))
+        >>> df.style.set_tooltips_class(name='tt-add', properties=[
+        ...     ('visibility', 'hidden'),
+        ...     ('position', 'absolute'),
+        ...     ('z-index', 1)])
+        """
+        if properties:
+            self.tooltips.class_properties = properties
+        if name:
+            self.tooltips.class_name = name
+        return self
+
     @doc(NDFrame.to_excel, klass="Styler")
     def to_excel(
         self,
@@ -246,7 +333,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"
@@ -540,6 +627,7 @@ def render(self, **kwargs) -> str:
         self._compute()
         # TODO: namespace all the pandas keys
         d = self._translate()
+        d = self.tooltips._translate_tooltips(self.data, self.uuid, d)
         # filter out empty styles, every cell will have a class
         # but the list of props may just be [['', '']].
         # so we have the nested anys below
@@ -609,6 +697,7 @@ def clear(self) -> None:
         Returns None.
         """
         self.ctx.clear()
+        self.tooltips = _Tooltips()
         self._todo = []
 
     def _compute(self):
@@ -1516,6 +1605,148 @@ def pipe(self, func: Callable, *args, **kwargs):
         return com.pipe(self, func, *args, **kwargs)
 
 
+class _Tooltips:
+    """
+    An extension to ``Styler`` that allows for and manipulates tooltips on hover
+    of table data-cells in the HTML result.
+
+    Parameters
+    ----------
+    css_name: str, default "pd-t"
+        Name of the CSS class that controls visualisation of tooltips.
+    css_props: list-like, default; see Notes
+        List of (attr, value) tuples defining properties of the CSS class.
+    tooltips: DataFrame, default empty
+        DataFrame of strings aligned with underlying ``Styler`` data for tooltip
+        display.
+
+    Notes
+    -----
+    The default properties for the tooltip CSS class are:
+
+        - visibility: hidden
+        - position: absolute
+        - z-index: 1
+        - background-color: black
+        - color: white
+        - transform: translate(-20px, -20px)
+
+    Hidden visibility is a key prerequisite to the hover functionality, and should
+    always be included in any manual properties specification.
+    """
+
+    def __init__(
+        self,
+        css_props: List[Tuple[str, Union[str, int, float]]] = [
+            ("visibility", "hidden"),
+            ("position", "absolute"),
+            ("z-index", 1),
+            ("background-color", "black"),
+            ("color", "white"),
+            ("transform", "translate(-20px, -20px)"),
+        ],
+        css_name: str = "pd-t",
+        tooltips: DataFrame = DataFrame(),
+    ):
+        self.class_name = css_name
+        self.class_properties = css_props
+        self.tt_data = tooltips
+        self.table_styles: List[Dict[str, Union[str, List[Tuple[str, str]]]]] = []
+
+    @property
+    def class_styles(self):
+        return [{"selector": f".{self.class_name}", "props": self.class_properties}]
+
+    def _translate_tooltips(self, styler_data, uuid, 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
+        ----------
+        styler_data : DataFrame
+            Underlying ``Styler`` DataFrame used for reindexing.
+        d : dict
+            The dictionary prior to final render
+        """
+        self.tt_data = (
+            self.tt_data.reindex_like(styler_data)
+            .dropna(how="all", axis=0)
+            .dropna(how="all", axis=1)
+        )
+        if self.tt_data.empty:
+            return d
+
+        def pseudo_css(uuid, row, col, name, text):
+            """
+            For every table data-cell that has a valid tooltip (not None, NaN or
+            empty string) must create two pseudo CSS entries for the specific
+            <td> element id which are added to overall table styles:
+            an on hover visibility change and a content change
+            dependent upon the user's chosen display string.
+
+            For example:
+                [{"selector": "T__row1_col1:hover .pd-t",
+                 "props": [("visibility", "visible")]},
+                {"selector": "T__row1_col1 .pd-t::after",
+                 "props": [("content", "Some Valid Text String")]}]
+
+            Returns
+            -------
+            pseudo_css : List
+            """
+            return [
+                {
+                    "selector": "#T_"
+                    + uuid
+                    + "row"
+                    + str(row)
+                    + "_col"
+                    + str(col)
+                    + f":hover .{name}",
+                    "props": [("visibility", "visible")],
+                },
+                {
+                    "selector": "#T_"
+                    + uuid
+                    + "row"
+                    + str(row)
+                    + "_col"
+                    + str(col)
+                    + f" .{name}::after",
+                    "props": [("content", f'"{text}"')],
+                },
+            ]
+
+        mask = (self.tt_data.isna()) | (self.tt_data.eq(""))  # empty string = no ttip
+        self.table_styles = [
+            d
+            for sublist in [
+                pseudo_css(uuid, i, j, self.class_name, str(self.tt_data.iloc[i, j]),)
+                for i, rn in enumerate(self.tt_data.index)
+                for j, cn in enumerate(self.tt_data.columns)
+                if not mask.iloc[i, j]
+            ]
+            for d in sublist
+        ]
+
+        if self.table_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.class_name}"></span>'
+                        )
+            d["table_styles"].extend(self.class_styles)
+            d["table_styles"].extend(self.table_styles)
+
+        return d
+
+
 def _is_visible(idx_row, idx_col, lengths) -> bool:
     """
     Index -> {(idx_row, idx_col): bool}).

pandas/tests/io/formats/test_style.py

@@ -1697,6 +1697,76 @@ def test_colspan_w3(self):
         s = Styler(df, uuid="_", cell_ids=False)
         assert '<th class="col_heading level0 col0" colspan="2">l0</th>' in s.render()
 
+    @pytest.mark.parametrize(
+        "ttips",
+        [
+            DataFrame(
+                data=[["Min", "Max"], [np.nan, ""]],
+                columns=["A", "B"],
+                index=["a", "b"],
+            ),
+            DataFrame(data=[["Max", "Min"]], columns=["B", "A"], index=["a"]),
+            DataFrame(
+                data=[["Min", "Max", None]], columns=["A", "B", "C"], index=["a"]
+            ),
+        ],
+    )
+    def test_tooltip_render(self, ttips):
+        # GH 21266
+        df = pd.DataFrame(data=[[0, 3], [1, 2]], columns=["A", "B"], index=["a", "b"])
+        s = Styler(df, uuid="_").set_tooltips(ttips).render()
+
+        # test tooltip table level class
+        assert "#T__ .pd-t {\n          visibility: hidden;\n" in s
+
+        # 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
+        )
+        assert (
+            '<td id="T__row0_col0" class="data row0 col0" >0<span class="pd-t">'
+            + "</span></td>"
+            in s
+        )
+
+        # test 'Max' tooltip added
+        assert (
+            "#T__ #T__row0_col1:hover .pd-t {\n          visibility: visible;\n    }  "
+            + '  #T__ #T__row0_col1 .pd-t::after {\n          content: "Max";\n    }'
+            in s
+        )
+        assert (
+            '<td id="T__row0_col1" class="data row0 col1" >3<span class="pd-t">'
+            + "</span></td>"
+            in s
+        )
+
+    def test_tooltip_ignored(self):
+        # GH 21266
+        df = pd.DataFrame(data=[[0, 1], [2, 3]])
+        s = (
+            Styler(df, uuid="_").set_tooltips_class("pd-t").render()
+        )  # no set_tooltips()
+        assert '<style  type="text/css" >\n</style>' in s
+        assert '<span class="pd-t"></span>' not in s
+
+    def test_tooltip_class(self):
+        # GH 21266
+        df = pd.DataFrame(data=[[0, 1], [2, 3]])
+        s = (
+            Styler(df, uuid="_")
+            .set_tooltips(DataFrame([["tooltip"]]))
+            .set_tooltips_class(name="other-class", properties=[("color", "green")])
+            .render()
+        )
+        assert "#T__ .other-class {\n          color: green;\n" in s
+        assert (
+            '#T__ #T__row0_col0 .other-class::after {\n          content: "tooltip";\n'
+            in s
+        )
+
 
 @td.skip_if_no_mpl
 class TestStylerMatplotlibDep: