Skip to content

DOC: fix docstring validation errors for pandas.io.formats.style.Styler #59607

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 4 commits into from
Aug 27, 2024
Merged

DOC: fix docstring validation errors for pandas.io.formats.style.Styler #59607

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
54d43a8
DOC: all pandas.io.formats.style.Styler docstring validation errors f…
hlakams Aug 26, 2024
175dd36
DOCS: base to_excel docstring template extended for pandas.io.formats…
hlakams Aug 26, 2024
dc5fa49
Merge branch 'main' into fix_docstring_pandas_styler
hlakams Aug 26, 2024
2011e5a
Merge branch 'main' into fix_docstring_pandas_styler
hlakams Aug 26, 2024
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
28 changes: 0 additions & 28 deletions ci/code_checks.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -305,34 +305,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
-i "pandas.errors.UnsupportedFunctionCall SA01" \
-i "pandas.errors.ValueLabelTypeMismatch SA01" \
-i "pandas.infer_freq SA01" \
-i "pandas.io.formats.style.Styler.apply RT03" \
-i "pandas.io.formats.style.Styler.apply_index RT03" \
-i "pandas.io.formats.style.Styler.background_gradient RT03" \
-i "pandas.io.formats.style.Styler.bar RT03,SA01" \
-i "pandas.io.formats.style.Styler.clear SA01" \
-i "pandas.io.formats.style.Styler.concat RT03,SA01" \
-i "pandas.io.formats.style.Styler.export RT03" \
-i "pandas.io.formats.style.Styler.from_custom_template SA01" \
-i "pandas.io.formats.style.Styler.hide RT03,SA01" \
-i "pandas.io.formats.style.Styler.highlight_between RT03" \
-i "pandas.io.formats.style.Styler.highlight_max RT03" \
-i "pandas.io.formats.style.Styler.highlight_min RT03" \
-i "pandas.io.formats.style.Styler.highlight_null RT03" \
-i "pandas.io.formats.style.Styler.highlight_quantile RT03" \
-i "pandas.io.formats.style.Styler.map RT03" \
-i "pandas.io.formats.style.Styler.map_index RT03" \
-i "pandas.io.formats.style.Styler.set_caption RT03,SA01" \
-i "pandas.io.formats.style.Styler.set_properties RT03,SA01" \
-i "pandas.io.formats.style.Styler.set_sticky RT03,SA01" \
-i "pandas.io.formats.style.Styler.set_table_attributes PR07,RT03" \
-i "pandas.io.formats.style.Styler.set_table_styles RT03" \
-i "pandas.io.formats.style.Styler.set_td_classes RT03" \
-i "pandas.io.formats.style.Styler.set_tooltips RT03,SA01" \
-i "pandas.io.formats.style.Styler.set_uuid PR07,RT03,SA01" \
-i "pandas.io.formats.style.Styler.text_gradient RT03" \
-i "pandas.io.formats.style.Styler.to_excel PR01" \
-i "pandas.io.formats.style.Styler.to_string SA01" \
-i "pandas.io.formats.style.Styler.use RT03" \
-i "pandas.io.json.build_table_schema PR07,RT03,SA01" \
-i "pandas.io.stata.StataReader.data_label SA01" \
-i "pandas.io.stata.StataReader.value_labels RT03,SA01" \
Expand Down
107 changes: 104 additions & 3 deletions pandas/io/formats/style.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
import copy
from functools import partial
import operator
import textwrap
from typing import (
TYPE_CHECKING,
overload,
Expand Down Expand Up @@ -306,6 +307,12 @@ def concat(self, other: Styler) -> Styler:
Returns
-------
Styler
Instance of class with specified Styler appended.

See Also
--------
Styler.clear : Reset the ``Styler``, removing any previously applied styles.
Styler.export : Export the styles applied to the current Styler.

Notes
-----
Expand Down Expand Up @@ -447,6 +454,15 @@ def set_tooltips(
Returns
-------
Styler
Instance of class with DataFrame set for strings on ``Styler``
generating ``:hover`` tooltips.

See Also
--------
Styler.set_table_attributes : Set the table attributes added to the
``<table>`` HTML element.
Styler.set_table_styles : Set the table styles included within the
``<style>`` HTML element.

Notes
-----
Expand Down Expand Up @@ -537,7 +553,14 @@ def set_tooltips(
klass="Styler",
storage_options=_shared_docs["storage_options"],
storage_options_versionadded="1.5.0",
extra_parameters="",
extra_parameters=textwrap.dedent(
"""\
encoding : str or None, default None
Unused parameter, present for compatibility.
verbose : str, default True
Optional unused parameter, present for compatibility.
"""
),
)
def to_excel(
self,
Expand All @@ -553,11 +576,11 @@ def to_excel(
startcol: int = 0,
engine: str | None = None,
merge_cells: ExcelWriterMergeCells = True,
encoding: str | None = None,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The ordering of these parameters should not change.

Copy link
Contributor Author

@hlakams hlakams Aug 26, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This function's parameters are out of order when used in the base to_excel template docstring (since var extra_parameters is substituted at its end). I'll roll back the current change and instead add optional params to the base to_excel template docstring to accommodate encoding and verbose.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Resolution for requested change is in 175dd36.

inf_rep: str = "inf",
verbose: bool = True,
freeze_panes: tuple[int, int] | None = None,
storage_options: StorageOptions | None = None,
encoding: str | None = None,
verbose: bool = True,
) -> None:
from pandas.io.formats.excel import ExcelFormatter

Expand Down Expand Up @@ -1456,6 +1479,10 @@ def to_string(
str or None
If `buf` is None, returns the result as a string. Otherwise returns `None`.

See Also
--------
DataFrame.to_string : Render a DataFrame to a console-friendly tabular output.

Examples
--------
>>> df = pd.DataFrame({"A": [1, 2], "B": [3, 4]})
Expand Down Expand Up @@ -1495,6 +1522,8 @@ def set_td_classes(self, classes: DataFrame) -> Styler:
Returns
-------
Styler
Instance of class with ``class`` attribute set for ``<td>``
HTML elements.

See Also
--------
Expand Down Expand Up @@ -1700,6 +1729,14 @@ def clear(self) -> None:

Returns None.

See Also
--------
Styler.apply : Apply a CSS-styling function column-wise, row-wise,
or table-wise.
Styler.export : Export the styles applied to the current Styler.
Styler.map : Apply a CSS-styling function elementwise.
Styler.use : Set the styles on the current Styler.

Examples
--------
>>> df = pd.DataFrame({"A": [1, 2], "B": [3, np.nan]})
Expand Down Expand Up @@ -1821,6 +1858,7 @@ def apply(
Returns
-------
Styler
Instance of class with CSS applied to its HTML representation.

See Also
--------
Expand Down Expand Up @@ -1941,6 +1979,7 @@ def apply_index(
Returns
-------
Styler
Instance of class with CSS applied to its HTML representation.

See Also
--------
Expand Down Expand Up @@ -2041,6 +2080,7 @@ def map(self, func: Callable, subset: Subset | None = None, **kwargs) -> Styler:
Returns
-------
Styler
Instance of class with CSS-styling function applied elementwise.

See Also
--------
Expand Down Expand Up @@ -2093,10 +2133,12 @@ def set_table_attributes(self, attributes: str) -> Styler:
Parameters
----------
attributes : str
Table attributes to be added to the ``<table>`` HTML element.

Returns
-------
Styler
Instance of class with specified table attributes set.

See Also
--------
Expand All @@ -2123,6 +2165,7 @@ def export(self) -> dict[str, Any]:
Returns
-------
dict
Contains data-independent (exportable) styles applied to current Styler.

See Also
--------
Expand Down Expand Up @@ -2199,6 +2242,7 @@ def use(self, styles: dict[str, Any]) -> Styler:
Returns
-------
Styler
Instance of class with defined styler attributes added.

See Also
--------
Expand Down Expand Up @@ -2246,10 +2290,19 @@ def set_uuid(self, uuid: str) -> Styler:
Parameters
----------
uuid : str
The uuid to be applied to ``id`` attributes of HTML elements.

Returns
-------
Styler
Instance of class with specified uuid for `id` attributes set.

See Also
--------
Styler.set_caption : Set the text added to a ``<caption>`` HTML element.
Styler.set_td_classes : Set the ``class`` attribute of ``<td>`` HTML elements.
Styler.set_tooltips : Set the DataFrame of strings on ``Styler`` generating
``:hover`` tooltips.

Notes
-----
Expand Down Expand Up @@ -2290,6 +2343,14 @@ def set_caption(self, caption: str | tuple | list) -> Styler:
Returns
-------
Styler
Instance of class with text set for ``<caption>`` HTML element.

See Also
--------
Styler.set_td_classes : Set the ``class`` attribute of ``<td>`` HTML elements.
Styler.set_tooltips : Set the DataFrame of strings on ``Styler`` generating
``:hover`` tooltips.
Styler.set_uuid : Set the uuid applied to ``id`` attributes of HTML elements.

Examples
--------
Expand Down Expand Up @@ -2336,6 +2397,13 @@ def set_sticky(
Returns
-------
Styler
Instance of class with CSS set for permanently displaying headers
in scrolling frame.

See Also
--------
Styler.set_properties : Set defined CSS-properties to each ``<td>``
HTML element for the given subset.

Notes
-----
Expand Down Expand Up @@ -2496,6 +2564,7 @@ def set_table_styles(
Returns
-------
Styler
Instance of class with specified table styles set.

See Also
--------
Expand Down Expand Up @@ -2627,6 +2696,13 @@ def hide(
Returns
-------
Styler
Instance of class with specified headers/rows/columns hidden from display.

See Also
--------
Styler.apply : Apply a CSS-styling function column-wise, row-wise,
or table-wise.
Styler.map : Apply a CSS-styling function elementwise.

Notes
-----
Expand Down Expand Up @@ -2865,6 +2941,7 @@ def background_gradient(
Returns
-------
Styler
Instance of class with {name} colored in gradient style.

See Also
--------
Expand Down Expand Up @@ -3002,6 +3079,13 @@ def set_properties(self, subset: Subset | None = None, **kwargs) -> Styler:
Returns
-------
Styler
Instance of class with CSS-properties set for each ``<td>`` HTML element
in the given subset

See Also
--------
Styler.set_sticky : Add CSS to permanently display the index or column
headers in a scrolling frame.

Notes
-----
Expand Down Expand Up @@ -3099,6 +3183,13 @@ def bar(
Returns
-------
Styler
Contains list-like attribute with bar chart data as formatted CSS.

See Also
--------
PlotAccessor.bar : Vertical bar plot.
PlotAccessor.line : Plot Series or DataFrame as lines.
PlotAccessor.pie : Generate a pie plot.

Notes
-----
Expand Down Expand Up @@ -3177,6 +3268,7 @@ def highlight_null(
Returns
-------
Styler
Instance of class where null values are highlighted with given style.

See Also
--------
Expand Down Expand Up @@ -3231,6 +3323,7 @@ def highlight_max(
Returns
-------
Styler
Instance of class where max value is highlighted in given style.

See Also
--------
Expand Down Expand Up @@ -3287,6 +3380,7 @@ def highlight_min(
Returns
-------
Styler
Instance of class where min value is highlighted in given style.

See Also
--------
Expand Down Expand Up @@ -3351,6 +3445,7 @@ def highlight_between(
Returns
-------
Styler
Instance of class with range highlighted in given style.

See Also
--------
Expand Down Expand Up @@ -3471,6 +3566,7 @@ def highlight_quantile(
Returns
-------
Styler
Instance of class where values in quantile highlighted with given style.

See Also
--------
Expand Down Expand Up @@ -3576,6 +3672,11 @@ def from_custom_template(
Has the correct ``env``,``template_html``, ``template_html_table`` and
``template_html_style`` class attributes set.

See Also
--------
Styler.export : Export the styles applied to the current Styler.
Styler.use : Set the styles on the current Styler.

Examples
--------
>>> from pandas.io.formats.style import Styler
Expand Down
Loading