From fa565dadea39e166059ff78dfd98c23793a567c3 Mon Sep 17 00:00:00 2001 From: "JHM Darbyshire (iMac)" Date: Thu, 18 Mar 2021 08:26:56 +0100 Subject: [PATCH 1/2] docs --- pandas/io/formats/style.py | 148 +++++++++++++++++++++++++------------ 1 file changed, 101 insertions(+), 47 deletions(-) diff --git a/pandas/io/formats/style.py b/pandas/io/formats/style.py index 3abb39d2194c0..20c08efceb9cf 100644 --- a/pandas/io/formats/style.py +++ b/pandas/io/formats/style.py @@ -217,8 +217,10 @@ def set_tooltips( css_class: Optional[str] = None, ) -> Styler: """ - Add string based tooltips that will appear in the `Styler` HTML result. These - tooltips are applicable only to`` elements. + Set the DataFrame of strings on ``Styler`` generating ``:hover`` tooltips. + + These string based tooltips are only applicable to ```` HTML elements, + and cannot be used for column or index headers. .. versionadded:: 1.3.0 @@ -227,7 +229,7 @@ def set_tooltips( 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 + Styler data. None, NaN values, and empty strings will be ignored and not affect the rendered HTML. props : list-like or str, optional List of (attr, value) tuples or a valid CSS string. If ``None`` adopts @@ -671,21 +673,33 @@ def format( def set_td_classes(self, classes: DataFrame) -> Styler: """ - Add string based CSS class names to data cells that will appear within the - `Styler` HTML result. These classes are added within specified `` elements. + Set the DataFrame of strings added to the ``class`` attribute of ```` + HTML elements. Parameters ---------- classes : DataFrame DataFrame containing strings that will be translated to CSS classes, - mapped by identical column and index values that must exist on the - underlying `Styler` data. None, NaN values, and empty strings will + mapped by identical column and index key 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 + See Also + -------- + Styler.set_table_styles: Set the table styles included within the ``' - '' + '' + '
' ' ' ' ' ' ' ' ' - ' ' + ' ' ' ' '
0
1
1
' """ @@ -736,7 +750,7 @@ def set_td_classes(self, classes: DataFrame) -> Styler: def render(self, **kwargs) -> str: """ - Render the built up styles to HTML. + Render the ``Styler`` including all applied styles to HTML. Parameters ---------- @@ -753,7 +767,7 @@ def render(self, **kwargs) -> str: Notes ----- - ``Styler`` objects have defined the ``_repr_html_`` method + Styler objects have defined the ``_repr_html_`` method which automatically calls ``self.render()`` when it's the last item in a Notebook cell. When calling ``Styler.render()`` directly, wrap the result in ``IPython.display.HTML`` to view @@ -779,7 +793,7 @@ def render(self, **kwargs) -> str: def _update_ctx(self, attrs: DataFrame) -> None: """ - Update the state of the Styler for data cells. + Update the state of the ``Styler`` for data cells. Collects a mapping of {index_label: [('', ''), ..]}. @@ -839,7 +853,7 @@ def __deepcopy__(self, memo) -> Styler: def clear(self) -> None: """ - Reset the styler, removing any previously applied styles. + Reset the ``Styler``, removing any previously applied styles. Returns None. """ @@ -923,10 +937,11 @@ def apply( Parameters ---------- func : function - ``func`` should take a Series or DataFrame (depending - on ``axis``), and return an object with the same shape. - Must return a DataFrame with identical index and - column labels or an ndarray with same shape as input when ``axis=None``. + ``func`` should take a Series if ``axis`` in [0,1] and return an object + of same length, also with identical index if the object is a Series. + ``func`` should take a DataFrame if ``axis`` is ``None`` and return either + an ndarray with the same shape or a DataFrame with identical columns and + index. .. versionchanged:: 1.3.0 @@ -944,13 +959,15 @@ def apply( ------- self : Styler + See Also + -------- + Styler.where: Apply CSS-styles based on a conditional function elementwise. + Styler.applymap: Apply a CSS-styling function elementwise. + Notes ----- - The output of ``func`` should be elements having CSS style as string or, + The elements of the output of ``func`` should be CSS styles as strings or, if nothing is to be applied to that element, an empty string or ``None``. - The output shape must match the input, i.e. if - ``x`` is the input row, column, or table (depending on ``axis``), - then ``func(x).shape == x.shape`` should be ``True``. This is similar to ``DataFrame.apply``, except that ``axis=None`` applies the function to the entire DataFrame at once, @@ -1001,8 +1018,8 @@ def applymap(self, func: Callable, subset=None, **kwargs) -> Styler: See Also -------- - Styler.where: Updates the HTML representation with a style which is - selected in accordance with the return value of a function. + Styler.where: Apply CSS-styles based on a conditional function elementwise. + Styler.apply: Apply a CSS-styling function column-wise, row-wise, or table-wise. Notes ----- @@ -1030,7 +1047,7 @@ def where( **kwargs, ) -> Styler: """ - Apply a function elementwise. + Apply CSS-styles based on a conditional function elementwise. Updates the HTML representation with a style which is selected in accordance with the return value of a function. @@ -1055,7 +1072,15 @@ def where( See Also -------- - Styler.applymap: Updates the HTML representation with the result. + Styler.applymap: Apply a CSS-styling function elementwise. + Styler.apply: Apply a CSS-styling function column-wise, row-wise, or table-wise. + + Examples + -------- + >>> def cond(v): + ... return v > 1 and v != 4 + >>> df = pd.DataFrame([[1, 2], [3, 4]]) + >>> df.style.where(cond, value='color:red;', other='font-size:2em;') """ if other is None: other = "" @@ -1092,10 +1117,9 @@ def set_precision(self, precision: int) -> Styler: def set_table_attributes(self, attributes: str) -> Styler: """ - Set the table attributes. + Set the table attributes added to the ```` HTML element. - These are the items that show up in the opening ``
`` tag - in addition to automatic (by default) id. + These are items in addition to automatic (by default) ``id`` attribute. Parameters ---------- @@ -1105,6 +1129,13 @@ def set_table_attributes(self, attributes: str) -> Styler: ------- self : Styler + See Also + -------- + Styler.set_table_styles: Set the table styles included within the ``