diff --git a/pandas/io/formats/style.py b/pandas/io/formats/style.py index 40803ff14e357..b1b31fef61b91 100644 --- a/pandas/io/formats/style.py +++ b/pandas/io/formats/style.py @@ -27,7 +27,10 @@ Scalar, ) from pandas.compat._optional import import_optional_dependency -from pandas.util._decorators import doc +from pandas.util._decorators import ( + Substitution, + doc, +) from pandas.util._exceptions import find_stack_level import pandas as pd @@ -78,6 +81,26 @@ def _mpl(func: Callable): raise ImportError(no_mpl_message.format(func.__name__)) +#### +# Shared Doc Strings + +subset = """ + subset : label, array-like, IndexSlice, optional + A valid 2d input to `DataFrame.loc[]`, or, in the case of a 1d input + or single key, to `DataFrame.loc[:, ]` where the columns are + prioritised, to limit ``data`` to *before* applying the function. +""" + +props = """ + props : str, default None + CSS properties to use for highlighting. If ``props`` is given, ``color`` + is not used. +""" + +# +### + + class Styler(StylerRenderer): r""" Helps style a DataFrame or Series according to the data with HTML and CSS. @@ -1302,6 +1325,7 @@ def _apply( self._update_ctx(result) return self + @Substitution(subset=subset) def apply( self, func: Callable, @@ -1332,10 +1356,7 @@ def apply( Apply to each column (``axis=0`` or ``'index'``), to each row (``axis=1`` or ``'columns'``), or to the entire DataFrame at once with ``axis=None``. - subset : label, array-like, IndexSlice, optional - A valid 2d input to `DataFrame.loc[]`, or, in the case of a 1d input - or single key, to `DataFrame.loc[:, ]` where the columns are - prioritised, to limit ``data`` to *before* applying the function. + %(subset)s **kwargs : dict Pass along to ``func``. @@ -1545,6 +1566,7 @@ def _applymap( self._update_ctx(result) return self + @Substitution(subset=subset) def applymap( self, func: Callable, subset: Subset | None = None, **kwargs ) -> Styler: @@ -1557,10 +1579,7 @@ def applymap( ---------- func : function ``func`` should take a scalar and return a string. - subset : label, array-like, IndexSlice, optional - A valid 2d input to `DataFrame.loc[]`, or, in the case of a 1d input - or single key, to `DataFrame.loc[:, ]` where the columns are - prioritised, to limit ``data`` to *before* applying the function. + %(subset)s **kwargs : dict Pass along to ``func``. @@ -1609,6 +1628,7 @@ def applymap( ) return self + @Substitution(subset=subset) def where( self, cond: Callable, @@ -1634,10 +1654,7 @@ def where( Applied when ``cond`` returns true. other : str Applied when ``cond`` returns false. - subset : label, array-like, IndexSlice, optional - A valid 2d input to `DataFrame.loc[]`, or, in the case of a 1d input - or single key, to `DataFrame.loc[:, ]` where the columns are - prioritised, to limit ``data`` to *before* applying the function. + %(subset)s **kwargs : dict Pass along to ``cond``. @@ -2527,6 +2544,7 @@ def hide( axis="{0 or 'index', 1 or 'columns', None}", text_threshold="", ) + @Substitution(subset=subset) def background_gradient( self, cmap="PuBu", @@ -2562,10 +2580,7 @@ def background_gradient( Apply to each column (``axis=0`` or ``'index'``), to each row (``axis=1`` or ``'columns'``), or to the entire DataFrame at once with ``axis=None``. - subset : label, array-like, IndexSlice, optional - A valid 2d input to `DataFrame.loc[]`, or, in the case of a 1d input - or single key, to `DataFrame.loc[:, ]` where the columns are - prioritised, to limit ``data`` to *before* applying the function. + %(subset)s text_color_threshold : float or int {text_threshold} Luminance threshold for determining text color in [0, 1]. Facilitates text @@ -2717,6 +2732,7 @@ def text_gradient( text_only=True, ) + @Substitution(subset=subset) def set_properties(self, subset: Subset | None = None, **kwargs) -> Styler: """ Set defined CSS-properties to each ```` HTML element within the given @@ -2724,10 +2740,7 @@ def set_properties(self, subset: Subset | None = None, **kwargs) -> Styler: Parameters ---------- - subset : label, array-like, IndexSlice, optional - A valid 2d input to `DataFrame.loc[]`, or, in the case of a 1d input - or single key, to `DataFrame.loc[:, ]` where the columns are - prioritised, to limit ``data`` to *before* applying the function. + %(subset)s **kwargs : dict A dictionary of property, value pairs to be set for each cell. @@ -2752,6 +2765,7 @@ def set_properties(self, subset: Subset | None = None, **kwargs) -> Styler: values = "".join([f"{p}: {v};" for p, v in kwargs.items()]) return self.applymap(lambda x: values, subset=subset) + @Substitution(subset=subset) def bar( self, subset: Subset | None = None, @@ -2773,10 +2787,7 @@ def bar( Parameters ---------- - subset : label, array-like, IndexSlice, optional - A valid 2d input to `DataFrame.loc[]`, or, in the case of a 1d input - or single key, to `DataFrame.loc[:, ]` where the columns are - prioritised, to limit ``data`` to *before* applying the function. + %(subset)s axis : {0 or 'index', 1 or 'columns', None}, default 0 Apply to each column (``axis=0`` or ``'index'``), to each row (``axis=1`` or ``'columns'``), or to the entire DataFrame at once @@ -2877,6 +2888,7 @@ def bar( return self + @Substitution(subset=subset, props=props) def highlight_null( self, null_color: str = "red", @@ -2889,17 +2901,9 @@ def highlight_null( Parameters ---------- null_color : str, default 'red' - subset : label, array-like, IndexSlice, optional - A valid 2d input to `DataFrame.loc[]`, or, in the case of a 1d input - or single key, to `DataFrame.loc[:, ]` where the columns are - prioritised, to limit ``data`` to *before* applying the function. - + %(subset)s .. versionadded:: 1.1.0 - - props : str, default None - CSS properties to use for highlighting. If ``props`` is given, ``color`` - is not used. - + %(props)s .. versionadded:: 1.3.0 Returns @@ -2921,6 +2925,7 @@ def f(data: DataFrame, props: str) -> np.ndarray: props = f"background-color: {null_color};" return self.apply(f, axis=None, subset=subset, props=props) + @Substitution(subset=subset, props=props) def highlight_max( self, subset: Subset | None = None, @@ -2933,20 +2938,14 @@ def highlight_max( Parameters ---------- - subset : label, array-like, IndexSlice, optional - A valid 2d input to `DataFrame.loc[]`, or, in the case of a 1d input - or single key, to `DataFrame.loc[:, ]` where the columns are - prioritised, to limit ``data`` to *before* applying the function. + %(subset)s color : str, default 'yellow' Background color to use for highlighting. axis : {0 or 'index', 1 or 'columns', None}, default 0 Apply to each column (``axis=0`` or ``'index'``), to each row (``axis=1`` or ``'columns'``), or to the entire DataFrame at once with ``axis=None``. - props : str, default None - CSS properties to use for highlighting. If ``props`` is given, ``color`` - is not used. - + %(props)s .. versionadded:: 1.3.0 Returns @@ -2970,6 +2969,7 @@ def highlight_max( props=props, ) + @Substitution(subset=subset, props=props) def highlight_min( self, subset: Subset | None = None, @@ -2982,20 +2982,14 @@ def highlight_min( Parameters ---------- - subset : label, array-like, IndexSlice, optional - A valid 2d input to `DataFrame.loc[]`, or, in the case of a 1d input - or single key, to `DataFrame.loc[:, ]` where the columns are - prioritised, to limit ``data`` to *before* applying the function. + %(subset)s color : str, default 'yellow' Background color to use for highlighting. axis : {0 or 'index', 1 or 'columns', None}, default 0 Apply to each column (``axis=0`` or ``'index'``), to each row (``axis=1`` or ``'columns'``), or to the entire DataFrame at once with ``axis=None``. - props : str, default None - CSS properties to use for highlighting. If ``props`` is given, ``color`` - is not used. - + %(props)s .. versionadded:: 1.3.0 Returns @@ -3019,6 +3013,7 @@ def highlight_min( props=props, ) + @Substitution(subset=subset, props=props) def highlight_between( self, subset: Subset | None = None, @@ -3036,10 +3031,7 @@ def highlight_between( Parameters ---------- - subset : label, array-like, IndexSlice, optional - A valid 2d input to `DataFrame.loc[]`, or, in the case of a 1d input - or single key, to `DataFrame.loc[:, ]` where the columns are - prioritised, to limit ``data`` to *before* applying the function. + %(subset)s color : str, default 'yellow' Background color to use for highlighting. axis : {0 or 'index', 1 or 'columns', None}, default 0 @@ -3051,10 +3043,7 @@ def highlight_between( Right bound for defining the range. inclusive : {'both', 'neither', 'left', 'right'} Identify whether bounds are closed or open. - props : str, default None - CSS properties to use for highlighting. If ``props`` is given, ``color`` - is not used. - + %(props)s Returns ------- self : Styler @@ -3128,6 +3117,7 @@ def highlight_between( inclusive=inclusive, ) + @Substitution(subset=subset, props=props) def highlight_quantile( self, subset: Subset | None = None, @@ -3146,10 +3136,7 @@ def highlight_quantile( Parameters ---------- - subset : label, array-like, IndexSlice, optional - A valid 2d input to `DataFrame.loc[]`, or, in the case of a 1d input - or single key, to `DataFrame.loc[:, ]` where the columns are - prioritised, to limit ``data`` to *before* applying the function. + %(subset)s color : str, default 'yellow' Background color to use for highlighting axis : {0 or 'index', 1 or 'columns', None}, default 0 @@ -3164,10 +3151,7 @@ def highlight_quantile( quantile estimation. inclusive : {'both', 'neither', 'left', 'right'} Identify whether quantile bounds are closed or open. - props : str, default None - CSS properties to use for highlighting. If ``props`` is given, ``color`` - is not used. - + %(props)s Returns ------- self : Styler