Skip to content

Commit 9ea3b12

Browse files
authored
DOC: substitute multiple entries for subset in style.py (#44454)
1 parent 9895311 commit 9ea3b12

File tree

1 file changed

+51
-67
lines changed

1 file changed

+51
-67
lines changed

pandas/io/formats/style.py

+51-67
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,10 @@
2828
WriteBuffer,
2929
)
3030
from pandas.compat._optional import import_optional_dependency
31-
from pandas.util._decorators import doc
31+
from pandas.util._decorators import (
32+
Substitution,
33+
doc,
34+
)
3235
from pandas.util._exceptions import find_stack_level
3336

3437
import pandas as pd
@@ -79,6 +82,26 @@ def _mpl(func: Callable):
7982
raise ImportError(no_mpl_message.format(func.__name__))
8083

8184

85+
####
86+
# Shared Doc Strings
87+
88+
subset = """
89+
subset : label, array-like, IndexSlice, optional
90+
A valid 2d input to `DataFrame.loc[<subset>]`, or, in the case of a 1d input
91+
or single key, to `DataFrame.loc[:, <subset>]` where the columns are
92+
prioritised, to limit ``data`` to *before* applying the function.
93+
"""
94+
95+
props = """
96+
props : str, default None
97+
CSS properties to use for highlighting. If ``props`` is given, ``color``
98+
is not used.
99+
"""
100+
101+
#
102+
###
103+
104+
82105
class Styler(StylerRenderer):
83106
r"""
84107
Helps style a DataFrame or Series according to the data with HTML and CSS.
@@ -1307,6 +1330,7 @@ def _apply(
13071330
self._update_ctx(result)
13081331
return self
13091332

1333+
@Substitution(subset=subset)
13101334
def apply(
13111335
self,
13121336
func: Callable,
@@ -1337,10 +1361,7 @@ def apply(
13371361
Apply to each column (``axis=0`` or ``'index'``), to each row
13381362
(``axis=1`` or ``'columns'``), or to the entire DataFrame at once
13391363
with ``axis=None``.
1340-
subset : label, array-like, IndexSlice, optional
1341-
A valid 2d input to `DataFrame.loc[<subset>]`, or, in the case of a 1d input
1342-
or single key, to `DataFrame.loc[:, <subset>]` where the columns are
1343-
prioritised, to limit ``data`` to *before* applying the function.
1364+
%(subset)s
13441365
**kwargs : dict
13451366
Pass along to ``func``.
13461367
@@ -1550,6 +1571,7 @@ def _applymap(
15501571
self._update_ctx(result)
15511572
return self
15521573

1574+
@Substitution(subset=subset)
15531575
def applymap(
15541576
self, func: Callable, subset: Subset | None = None, **kwargs
15551577
) -> Styler:
@@ -1562,10 +1584,7 @@ def applymap(
15621584
----------
15631585
func : function
15641586
``func`` should take a scalar and return a string.
1565-
subset : label, array-like, IndexSlice, optional
1566-
A valid 2d input to `DataFrame.loc[<subset>]`, or, in the case of a 1d input
1567-
or single key, to `DataFrame.loc[:, <subset>]` where the columns are
1568-
prioritised, to limit ``data`` to *before* applying the function.
1587+
%(subset)s
15691588
**kwargs : dict
15701589
Pass along to ``func``.
15711590
@@ -1614,6 +1633,7 @@ def applymap(
16141633
)
16151634
return self
16161635

1636+
@Substitution(subset=subset)
16171637
def where(
16181638
self,
16191639
cond: Callable,
@@ -1639,10 +1659,7 @@ def where(
16391659
Applied when ``cond`` returns true.
16401660
other : str
16411661
Applied when ``cond`` returns false.
1642-
subset : label, array-like, IndexSlice, optional
1643-
A valid 2d input to `DataFrame.loc[<subset>]`, or, in the case of a 1d input
1644-
or single key, to `DataFrame.loc[:, <subset>]` where the columns are
1645-
prioritised, to limit ``data`` to *before* applying the function.
1662+
%(subset)s
16461663
**kwargs : dict
16471664
Pass along to ``cond``.
16481665
@@ -2532,6 +2549,7 @@ def hide(
25322549
axis="{0 or 'index', 1 or 'columns', None}",
25332550
text_threshold="",
25342551
)
2552+
@Substitution(subset=subset)
25352553
def background_gradient(
25362554
self,
25372555
cmap="PuBu",
@@ -2567,10 +2585,7 @@ def background_gradient(
25672585
Apply to each column (``axis=0`` or ``'index'``), to each row
25682586
(``axis=1`` or ``'columns'``), or to the entire DataFrame at once
25692587
with ``axis=None``.
2570-
subset : label, array-like, IndexSlice, optional
2571-
A valid 2d input to `DataFrame.loc[<subset>]`, or, in the case of a 1d input
2572-
or single key, to `DataFrame.loc[:, <subset>]` where the columns are
2573-
prioritised, to limit ``data`` to *before* applying the function.
2588+
%(subset)s
25742589
text_color_threshold : float or int
25752590
{text_threshold}
25762591
Luminance threshold for determining text color in [0, 1]. Facilitates text
@@ -2722,17 +2737,15 @@ def text_gradient(
27222737
text_only=True,
27232738
)
27242739

2740+
@Substitution(subset=subset)
27252741
def set_properties(self, subset: Subset | None = None, **kwargs) -> Styler:
27262742
"""
27272743
Set defined CSS-properties to each ``<td>`` HTML element within the given
27282744
subset.
27292745
27302746
Parameters
27312747
----------
2732-
subset : label, array-like, IndexSlice, optional
2733-
A valid 2d input to `DataFrame.loc[<subset>]`, or, in the case of a 1d input
2734-
or single key, to `DataFrame.loc[:, <subset>]` where the columns are
2735-
prioritised, to limit ``data`` to *before* applying the function.
2748+
%(subset)s
27362749
**kwargs : dict
27372750
A dictionary of property, value pairs to be set for each cell.
27382751
@@ -2757,6 +2770,7 @@ def set_properties(self, subset: Subset | None = None, **kwargs) -> Styler:
27572770
values = "".join([f"{p}: {v};" for p, v in kwargs.items()])
27582771
return self.applymap(lambda x: values, subset=subset)
27592772

2773+
@Substitution(subset=subset)
27602774
def bar(
27612775
self,
27622776
subset: Subset | None = None,
@@ -2778,10 +2792,7 @@ def bar(
27782792
27792793
Parameters
27802794
----------
2781-
subset : label, array-like, IndexSlice, optional
2782-
A valid 2d input to `DataFrame.loc[<subset>]`, or, in the case of a 1d input
2783-
or single key, to `DataFrame.loc[:, <subset>]` where the columns are
2784-
prioritised, to limit ``data`` to *before* applying the function.
2795+
%(subset)s
27852796
axis : {0 or 'index', 1 or 'columns', None}, default 0
27862797
Apply to each column (``axis=0`` or ``'index'``), to each row
27872798
(``axis=1`` or ``'columns'``), or to the entire DataFrame at once
@@ -2882,6 +2893,7 @@ def bar(
28822893

28832894
return self
28842895

2896+
@Substitution(subset=subset, props=props)
28852897
def highlight_null(
28862898
self,
28872899
null_color: str = "red",
@@ -2894,17 +2906,9 @@ def highlight_null(
28942906
Parameters
28952907
----------
28962908
null_color : str, default 'red'
2897-
subset : label, array-like, IndexSlice, optional
2898-
A valid 2d input to `DataFrame.loc[<subset>]`, or, in the case of a 1d input
2899-
or single key, to `DataFrame.loc[:, <subset>]` where the columns are
2900-
prioritised, to limit ``data`` to *before* applying the function.
2901-
2909+
%(subset)s
29022910
.. versionadded:: 1.1.0
2903-
2904-
props : str, default None
2905-
CSS properties to use for highlighting. If ``props`` is given, ``color``
2906-
is not used.
2907-
2911+
%(props)s
29082912
.. versionadded:: 1.3.0
29092913
29102914
Returns
@@ -2926,6 +2930,7 @@ def f(data: DataFrame, props: str) -> np.ndarray:
29262930
props = f"background-color: {null_color};"
29272931
return self.apply(f, axis=None, subset=subset, props=props)
29282932

2933+
@Substitution(subset=subset, props=props)
29292934
def highlight_max(
29302935
self,
29312936
subset: Subset | None = None,
@@ -2938,20 +2943,14 @@ def highlight_max(
29382943
29392944
Parameters
29402945
----------
2941-
subset : label, array-like, IndexSlice, optional
2942-
A valid 2d input to `DataFrame.loc[<subset>]`, or, in the case of a 1d input
2943-
or single key, to `DataFrame.loc[:, <subset>]` where the columns are
2944-
prioritised, to limit ``data`` to *before* applying the function.
2946+
%(subset)s
29452947
color : str, default 'yellow'
29462948
Background color to use for highlighting.
29472949
axis : {0 or 'index', 1 or 'columns', None}, default 0
29482950
Apply to each column (``axis=0`` or ``'index'``), to each row
29492951
(``axis=1`` or ``'columns'``), or to the entire DataFrame at once
29502952
with ``axis=None``.
2951-
props : str, default None
2952-
CSS properties to use for highlighting. If ``props`` is given, ``color``
2953-
is not used.
2954-
2953+
%(props)s
29552954
.. versionadded:: 1.3.0
29562955
29572956
Returns
@@ -2975,6 +2974,7 @@ def highlight_max(
29752974
props=props,
29762975
)
29772976

2977+
@Substitution(subset=subset, props=props)
29782978
def highlight_min(
29792979
self,
29802980
subset: Subset | None = None,
@@ -2987,20 +2987,14 @@ def highlight_min(
29872987
29882988
Parameters
29892989
----------
2990-
subset : label, array-like, IndexSlice, optional
2991-
A valid 2d input to `DataFrame.loc[<subset>]`, or, in the case of a 1d input
2992-
or single key, to `DataFrame.loc[:, <subset>]` where the columns are
2993-
prioritised, to limit ``data`` to *before* applying the function.
2990+
%(subset)s
29942991
color : str, default 'yellow'
29952992
Background color to use for highlighting.
29962993
axis : {0 or 'index', 1 or 'columns', None}, default 0
29972994
Apply to each column (``axis=0`` or ``'index'``), to each row
29982995
(``axis=1`` or ``'columns'``), or to the entire DataFrame at once
29992996
with ``axis=None``.
3000-
props : str, default None
3001-
CSS properties to use for highlighting. If ``props`` is given, ``color``
3002-
is not used.
3003-
2997+
%(props)s
30042998
.. versionadded:: 1.3.0
30052999
30063000
Returns
@@ -3024,6 +3018,7 @@ def highlight_min(
30243018
props=props,
30253019
)
30263020

3021+
@Substitution(subset=subset, props=props)
30273022
def highlight_between(
30283023
self,
30293024
subset: Subset | None = None,
@@ -3041,10 +3036,7 @@ def highlight_between(
30413036
30423037
Parameters
30433038
----------
3044-
subset : label, array-like, IndexSlice, optional
3045-
A valid 2d input to `DataFrame.loc[<subset>]`, or, in the case of a 1d input
3046-
or single key, to `DataFrame.loc[:, <subset>]` where the columns are
3047-
prioritised, to limit ``data`` to *before* applying the function.
3039+
%(subset)s
30483040
color : str, default 'yellow'
30493041
Background color to use for highlighting.
30503042
axis : {0 or 'index', 1 or 'columns', None}, default 0
@@ -3056,10 +3048,7 @@ def highlight_between(
30563048
Right bound for defining the range.
30573049
inclusive : {'both', 'neither', 'left', 'right'}
30583050
Identify whether bounds are closed or open.
3059-
props : str, default None
3060-
CSS properties to use for highlighting. If ``props`` is given, ``color``
3061-
is not used.
3062-
3051+
%(props)s
30633052
Returns
30643053
-------
30653054
self : Styler
@@ -3133,6 +3122,7 @@ def highlight_between(
31333122
inclusive=inclusive,
31343123
)
31353124

3125+
@Substitution(subset=subset, props=props)
31363126
def highlight_quantile(
31373127
self,
31383128
subset: Subset | None = None,
@@ -3151,10 +3141,7 @@ def highlight_quantile(
31513141
31523142
Parameters
31533143
----------
3154-
subset : label, array-like, IndexSlice, optional
3155-
A valid 2d input to `DataFrame.loc[<subset>]`, or, in the case of a 1d input
3156-
or single key, to `DataFrame.loc[:, <subset>]` where the columns are
3157-
prioritised, to limit ``data`` to *before* applying the function.
3144+
%(subset)s
31583145
color : str, default 'yellow'
31593146
Background color to use for highlighting
31603147
axis : {0 or 'index', 1 or 'columns', None}, default 0
@@ -3169,10 +3156,7 @@ def highlight_quantile(
31693156
quantile estimation.
31703157
inclusive : {'both', 'neither', 'left', 'right'}
31713158
Identify whether quantile bounds are closed or open.
3172-
props : str, default None
3173-
CSS properties to use for highlighting. If ``props`` is given, ``color``
3174-
is not used.
3175-
3159+
%(props)s
31763160
Returns
31773161
-------
31783162
self : Styler

0 commit comments

Comments
 (0)