Skip to content

DOC: substitute multiple entries for subset in style.py #44454

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Nov 20, 2021
Merged

DOC: substitute multiple entries for subset in style.py #44454

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
997be7c
Substitute doc
attack68 Nov 14, 2021
cdf70a1
fix build error
attack68 Nov 15, 2021
9b9c08d
add substitutions for props
attack68 Nov 15, 2021
4ad4b3f
add substitutions for props
attack68 Nov 16, 2021
136ba52
fix line break
attack68 Nov 16, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
118 changes: 51 additions & 67 deletions pandas/io/formats/style.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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[<subset>]`, or, in the case of a 1d input
or single key, to `DataFrame.loc[:, <subset>]` 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.
Expand Down Expand Up @@ -1302,6 +1325,7 @@ def _apply(
self._update_ctx(result)
return self

@Substitution(subset=subset)
def apply(
self,
func: Callable,
Expand Down Expand Up @@ -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[<subset>]`, or, in the case of a 1d input
or single key, to `DataFrame.loc[:, <subset>]` where the columns are
prioritised, to limit ``data`` to *before* applying the function.
%(subset)s
**kwargs : dict
Pass along to ``func``.

Expand Down Expand Up @@ -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:
Expand All @@ -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[<subset>]`, or, in the case of a 1d input
or single key, to `DataFrame.loc[:, <subset>]` where the columns are
prioritised, to limit ``data`` to *before* applying the function.
%(subset)s
**kwargs : dict
Pass along to ``func``.

Expand Down Expand Up @@ -1609,6 +1628,7 @@ def applymap(
)
return self

@Substitution(subset=subset)
def where(
self,
cond: Callable,
Expand All @@ -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[<subset>]`, or, in the case of a 1d input
or single key, to `DataFrame.loc[:, <subset>]` where the columns are
prioritised, to limit ``data`` to *before* applying the function.
%(subset)s
**kwargs : dict
Pass along to ``cond``.

Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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[<subset>]`, or, in the case of a 1d input
or single key, to `DataFrame.loc[:, <subset>]` 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
Expand Down Expand Up @@ -2717,17 +2732,15 @@ 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 ``<td>`` HTML element within the given
subset.

Parameters
----------
subset : label, array-like, IndexSlice, optional
A valid 2d input to `DataFrame.loc[<subset>]`, or, in the case of a 1d input
or single key, to `DataFrame.loc[:, <subset>]` 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.

Expand All @@ -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,
Expand All @@ -2773,10 +2787,7 @@ def bar(

Parameters
----------
subset : label, array-like, IndexSlice, optional
A valid 2d input to `DataFrame.loc[<subset>]`, or, in the case of a 1d input
or single key, to `DataFrame.loc[:, <subset>]` 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
Expand Down Expand Up @@ -2877,6 +2888,7 @@ def bar(

return self

@Substitution(subset=subset, props=props)
def highlight_null(
self,
null_color: str = "red",
Expand All @@ -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[<subset>]`, or, in the case of a 1d input
or single key, to `DataFrame.loc[:, <subset>]` 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
Expand All @@ -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,
Expand All @@ -2933,20 +2938,14 @@ def highlight_max(

Parameters
----------
subset : label, array-like, IndexSlice, optional
A valid 2d input to `DataFrame.loc[<subset>]`, or, in the case of a 1d input
or single key, to `DataFrame.loc[:, <subset>]` 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
Expand All @@ -2970,6 +2969,7 @@ def highlight_max(
props=props,
)

@Substitution(subset=subset, props=props)
def highlight_min(
self,
subset: Subset | None = None,
Expand All @@ -2982,20 +2982,14 @@ def highlight_min(

Parameters
----------
subset : label, array-like, IndexSlice, optional
A valid 2d input to `DataFrame.loc[<subset>]`, or, in the case of a 1d input
or single key, to `DataFrame.loc[:, <subset>]` 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
Expand All @@ -3019,6 +3013,7 @@ def highlight_min(
props=props,
)

@Substitution(subset=subset, props=props)
def highlight_between(
self,
subset: Subset | None = None,
Expand All @@ -3036,10 +3031,7 @@ def highlight_between(

Parameters
----------
subset : label, array-like, IndexSlice, optional
A valid 2d input to `DataFrame.loc[<subset>]`, or, in the case of a 1d input
or single key, to `DataFrame.loc[:, <subset>]` 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
Expand All @@ -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
Expand Down Expand Up @@ -3128,6 +3117,7 @@ def highlight_between(
inclusive=inclusive,
)

@Substitution(subset=subset, props=props)
def highlight_quantile(
self,
subset: Subset | None = None,
Expand All @@ -3146,10 +3136,7 @@ def highlight_quantile(

Parameters
----------
subset : label, array-like, IndexSlice, optional
A valid 2d input to `DataFrame.loc[<subset>]`, or, in the case of a 1d input
or single key, to `DataFrame.loc[:, <subset>]` 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
Expand All @@ -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
Expand Down