From 997be7c141dbeaa03890b7294ab4b57d89a10a2f Mon Sep 17 00:00:00 2001 From: "JHM Darbyshire (iMac)" Date: Sun, 14 Nov 2021 20:11:13 +0100 Subject: [PATCH 1/5] Substitute doc --- pandas/io/formats/style.py | 84 ++++++++++++++++++-------------------- 1 file changed, 39 insertions(+), 45 deletions(-) diff --git a/pandas/io/formats/style.py b/pandas/io/formats/style.py index 40803ff14e357..1b11a3ff97707 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,19 @@ 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. +""" +# +### + + class Styler(StylerRenderer): r""" Helps style a DataFrame or Series according to the data with HTML and CSS. @@ -1302,6 +1318,7 @@ def _apply( self._update_ctx(result) return self + @Substitution(subset=subset) def apply( self, func: Callable, @@ -1332,10 +1349,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 +1559,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 +1572,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 +1621,7 @@ def applymap( ) return self + @Substitution(subset=subset) def where( self, cond: Callable, @@ -1634,10 +1647,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 +2537,7 @@ def hide( axis="{0 or 'index', 1 or 'columns', None}", text_threshold="", ) + @Substitution(subset=subset) def background_gradient( self, cmap="PuBu", @@ -2562,10 +2573,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 +2725,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 +2733,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 +2758,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 +2780,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 +2881,7 @@ def bar( return self + @Substitution(subset=subset) def highlight_null( self, null_color: str = "red", @@ -2889,10 +2894,7 @@ 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 @@ -2921,6 +2923,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) def highlight_max( self, subset: Subset | None = None, @@ -2933,10 +2936,7 @@ 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 @@ -2970,6 +2970,7 @@ def highlight_max( props=props, ) + @Substitution(subset=subset) def highlight_min( self, subset: Subset | None = None, @@ -2982,10 +2983,7 @@ 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 @@ -3019,6 +3017,7 @@ def highlight_min( props=props, ) + @Substitution(subset=subset) def highlight_between( self, subset: Subset | None = None, @@ -3036,10 +3035,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 @@ -3128,6 +3124,7 @@ def highlight_between( inclusive=inclusive, ) + @Substitution(subset=subset) def highlight_quantile( self, subset: Subset | None = None, @@ -3146,10 +3143,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 From cdf70a1e0e5d863760c2c70c909731b0c3379d95 Mon Sep 17 00:00:00 2001 From: "JHM Darbyshire (iMac)" Date: Mon, 15 Nov 2021 18:03:55 +0100 Subject: [PATCH 2/5] fix build error --- pandas/io/formats/style.py | 1 - 1 file changed, 1 deletion(-) diff --git a/pandas/io/formats/style.py b/pandas/io/formats/style.py index 1b11a3ff97707..6e4a4a208521f 100644 --- a/pandas/io/formats/style.py +++ b/pandas/io/formats/style.py @@ -2895,7 +2895,6 @@ def highlight_null( ---------- null_color : str, default 'red' %(subset)s - .. versionadded:: 1.1.0 props : str, default None From 9b9c08d4afd9566da2214511012bdba951592449 Mon Sep 17 00:00:00 2001 From: "JHM Darbyshire (iMac)" Date: Mon, 15 Nov 2021 18:11:15 +0100 Subject: [PATCH 3/5] add substitutions for props --- pandas/io/formats/style.py | 40 ++++++++++++++++---------------------- 1 file changed, 17 insertions(+), 23 deletions(-) diff --git a/pandas/io/formats/style.py b/pandas/io/formats/style.py index 6e4a4a208521f..a364eb3c9c23e 100644 --- a/pandas/io/formats/style.py +++ b/pandas/io/formats/style.py @@ -90,6 +90,13 @@ def _mpl(func: Callable): 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. +""" + # ### @@ -2881,7 +2888,7 @@ def bar( return self - @Substitution(subset=subset) + @Substitution(subset=subset, props=props) def highlight_null( self, null_color: str = "red", @@ -2897,10 +2904,7 @@ def highlight_null( %(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 @@ -2922,7 +2926,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) + @Substitution(subset=subset, props=props) def highlight_max( self, subset: Subset | None = None, @@ -2942,10 +2946,7 @@ def highlight_max( 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 @@ -2969,7 +2970,7 @@ def highlight_max( props=props, ) - @Substitution(subset=subset) + @Substitution(subset=subset, props=props) def highlight_min( self, subset: Subset | None = None, @@ -2989,10 +2990,7 @@ def highlight_min( 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 @@ -3016,7 +3014,7 @@ def highlight_min( props=props, ) - @Substitution(subset=subset) + @Substitution(subset=subset, props=props) def highlight_between( self, subset: Subset | None = None, @@ -3046,9 +3044,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 ------- @@ -3123,7 +3119,7 @@ def highlight_between( inclusive=inclusive, ) - @Substitution(subset=subset) + @Substitution(subset=subset, props=props) def highlight_quantile( self, subset: Subset | None = None, @@ -3157,9 +3153,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 ------- From 4ad4b3f4a75b5139166e8d4051885342adb52b54 Mon Sep 17 00:00:00 2001 From: "JHM Darbyshire (iMac)" Date: Tue, 16 Nov 2021 07:21:13 +0100 Subject: [PATCH 4/5] add substitutions for props --- pandas/io/formats/style.py | 2 -- 1 file changed, 2 deletions(-) diff --git a/pandas/io/formats/style.py b/pandas/io/formats/style.py index a364eb3c9c23e..35c409f85fab4 100644 --- a/pandas/io/formats/style.py +++ b/pandas/io/formats/style.py @@ -3045,7 +3045,6 @@ def highlight_between( inclusive : {'both', 'neither', 'left', 'right'} Identify whether bounds are closed or open. %(props)s - Returns ------- self : Styler @@ -3154,7 +3153,6 @@ def highlight_quantile( inclusive : {'both', 'neither', 'left', 'right'} Identify whether quantile bounds are closed or open. %(props)s - Returns ------- self : Styler From 136ba5257c79e835f5d8103737b2736838dc3be6 Mon Sep 17 00:00:00 2001 From: "JHM Darbyshire (iMac)" Date: Tue, 16 Nov 2021 07:23:59 +0100 Subject: [PATCH 5/5] fix line break --- pandas/io/formats/style.py | 1 - 1 file changed, 1 deletion(-) diff --git a/pandas/io/formats/style.py b/pandas/io/formats/style.py index 35c409f85fab4..b1b31fef61b91 100644 --- a/pandas/io/formats/style.py +++ b/pandas/io/formats/style.py @@ -2903,7 +2903,6 @@ def highlight_null( null_color : str, default 'red' %(subset)s .. versionadded:: 1.1.0 - %(props)s .. versionadded:: 1.3.0