Skip to content

Commit 7c36579

Browse files
hlakamshlakams
authored
DOC: fix docstring validation errors for pandas.io.formats.style.Styler (#59607)
* DOC: all pandas.io.formats.style.Styler docstring validation errors fixed * DOCS: base to_excel docstring template extended for pandas.io.formats.style.Styler.to_excel
1 parent bd81fef commit 7c36579

File tree

3 files changed

+111
-29
lines changed

3 files changed

+111
-29
lines changed

‎ci/code_checks.sh‎

Lines changed: 0 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -294,34 +294,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
294294
-i "pandas.errors.UnsupportedFunctionCall SA01" \
295295
-i "pandas.errors.ValueLabelTypeMismatch SA01" \
296296
-i "pandas.infer_freq SA01" \
297-
-i "pandas.io.formats.style.Styler.apply RT03" \
298-
-i "pandas.io.formats.style.Styler.apply_index RT03" \
299-
-i "pandas.io.formats.style.Styler.background_gradient RT03" \
300-
-i "pandas.io.formats.style.Styler.bar RT03,SA01" \
301-
-i "pandas.io.formats.style.Styler.clear SA01" \
302-
-i "pandas.io.formats.style.Styler.concat RT03,SA01" \
303-
-i "pandas.io.formats.style.Styler.export RT03" \
304-
-i "pandas.io.formats.style.Styler.from_custom_template SA01" \
305-
-i "pandas.io.formats.style.Styler.hide RT03,SA01" \
306-
-i "pandas.io.formats.style.Styler.highlight_between RT03" \
307-
-i "pandas.io.formats.style.Styler.highlight_max RT03" \
308-
-i "pandas.io.formats.style.Styler.highlight_min RT03" \
309-
-i "pandas.io.formats.style.Styler.highlight_null RT03" \
310-
-i "pandas.io.formats.style.Styler.highlight_quantile RT03" \
311-
-i "pandas.io.formats.style.Styler.map RT03" \
312-
-i "pandas.io.formats.style.Styler.map_index RT03" \
313-
-i "pandas.io.formats.style.Styler.set_caption RT03,SA01" \
314-
-i "pandas.io.formats.style.Styler.set_properties RT03,SA01" \
315-
-i "pandas.io.formats.style.Styler.set_sticky RT03,SA01" \
316-
-i "pandas.io.formats.style.Styler.set_table_attributes PR07,RT03" \
317-
-i "pandas.io.formats.style.Styler.set_table_styles RT03" \
318-
-i "pandas.io.formats.style.Styler.set_td_classes RT03" \
319-
-i "pandas.io.formats.style.Styler.set_tooltips RT03,SA01" \
320-
-i "pandas.io.formats.style.Styler.set_uuid PR07,RT03,SA01" \
321-
-i "pandas.io.formats.style.Styler.text_gradient RT03" \
322-
-i "pandas.io.formats.style.Styler.to_excel PR01" \
323-
-i "pandas.io.formats.style.Styler.to_string SA01" \
324-
-i "pandas.io.formats.style.Styler.use RT03" \
325297
-i "pandas.io.json.build_table_schema PR07,RT03,SA01" \
326298
-i "pandas.io.stata.StataReader.data_label SA01" \
327299
-i "pandas.io.stata.StataReader.value_labels RT03,SA01" \

‎pandas/core/generic.py‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2123,11 +2123,13 @@ def _repr_data_resource_(self):
21232123
klass="object",
21242124
storage_options=_shared_docs["storage_options"],
21252125
storage_options_versionadded="1.2.0",
2126+
encoding_parameter="",
2127+
verbose_parameter="",
21262128
extra_parameters=textwrap.dedent(
21272129
"""\
21282130
engine_kwargs : dict, optional
21292131
Arbitrary keyword arguments passed to excel engine.
2130-
"""
2132+
"""
21312133
),
21322134
)
21332135
def to_excel(
@@ -2196,9 +2198,11 @@ def to_excel(
21962198
21972199
merge_cells : bool, default True
21982200
Write MultiIndex and Hierarchical Rows as merged cells.
2201+
{encoding_parameter}
21992202
inf_rep : str, default 'inf'
22002203
Representation for infinity (there is no native representation for
22012204
infinity in Excel).
2205+
{verbose_parameter}
22022206
freeze_panes : tuple of int (length 2), optional
22032207
Specifies the one-based bottommost row and rightmost column that
22042208
is to be frozen.

‎pandas/io/formats/style.py‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
import copy
88
from functools import partial
99
import operator
10+
import textwrap
1011
from typing import (
1112
TYPE_CHECKING,
1213
overload,
@@ -306,6 +307,12 @@ def concat(self, other: Styler) -> Styler:
306307
Returns
307308
-------
308309
Styler
310+
Instance of class with specified Styler appended.
311+
312+
See Also
313+
--------
314+
Styler.clear : Reset the ``Styler``, removing any previously applied styles.
315+
Styler.export : Export the styles applied to the current Styler.
309316
310317
Notes
311318
-----
@@ -447,6 +454,15 @@ def set_tooltips(
447454
Returns
448455
-------
449456
Styler
457+
Instance of class with DataFrame set for strings on ``Styler``
458+
generating ``:hover`` tooltips.
459+
460+
See Also
461+
--------
462+
Styler.set_table_attributes : Set the table attributes added to the
463+
``<table>`` HTML element.
464+
Styler.set_table_styles : Set the table styles included within the
465+
``<style>`` HTML element.
450466
451467
Notes
452468
-----
@@ -537,6 +553,18 @@ def set_tooltips(
537553
klass="Styler",
538554
storage_options=_shared_docs["storage_options"],
539555
storage_options_versionadded="1.5.0",
556+
encoding_parameter=textwrap.dedent(
557+
"""\
558+
encoding : str or None, default None
559+
Unused parameter, present for compatibility.
560+
"""
561+
),
562+
verbose_parameter=textwrap.dedent(
563+
"""\
564+
verbose : str, default True
565+
Optional unused parameter, present for compatibility.
566+
"""
567+
),
540568
extra_parameters="",
541569
)
542570
def to_excel(
@@ -1456,6 +1484,10 @@ def to_string(
14561484
str or None
14571485
If `buf` is None, returns the result as a string. Otherwise returns `None`.
14581486
1487+
See Also
1488+
--------
1489+
DataFrame.to_string : Render a DataFrame to a console-friendly tabular output.
1490+
14591491
Examples
14601492
--------
14611493
>>> df = pd.DataFrame({"A": [1, 2], "B": [3, 4]})
@@ -1495,6 +1527,8 @@ def set_td_classes(self, classes: DataFrame) -> Styler:
14951527
Returns
14961528
-------
14971529
Styler
1530+
Instance of class with ``class`` attribute set for ``<td>``
1531+
HTML elements.
14981532
14991533
See Also
15001534
--------
@@ -1700,6 +1734,14 @@ def clear(self) -> None:
17001734
17011735
Returns None.
17021736
1737+
See Also
1738+
--------
1739+
Styler.apply : Apply a CSS-styling function column-wise, row-wise,
1740+
or table-wise.
1741+
Styler.export : Export the styles applied to the current Styler.
1742+
Styler.map : Apply a CSS-styling function elementwise.
1743+
Styler.use : Set the styles on the current Styler.
1744+
17031745
Examples
17041746
--------
17051747
>>> df = pd.DataFrame({"A": [1, 2], "B": [3, np.nan]})
@@ -1821,6 +1863,7 @@ def apply(
18211863
Returns
18221864
-------
18231865
Styler
1866+
Instance of class with CSS applied to its HTML representation.
18241867
18251868
See Also
18261869
--------
@@ -1941,6 +1984,7 @@ def apply_index(
19411984
Returns
19421985
-------
19431986
Styler
1987+
Instance of class with CSS applied to its HTML representation.
19441988
19451989
See Also
19461990
--------
@@ -2041,6 +2085,7 @@ def map(self, func: Callable, subset: Subset | None = None, **kwargs) -> Styler:
20412085
Returns
20422086
-------
20432087
Styler
2088+
Instance of class with CSS-styling function applied elementwise.
20442089
20452090
See Also
20462091
--------
@@ -2093,10 +2138,12 @@ def set_table_attributes(self, attributes: str) -> Styler:
20932138
Parameters
20942139
----------
20952140
attributes : str
2141+
Table attributes to be added to the ``<table>`` HTML element.
20962142
20972143
Returns
20982144
-------
20992145
Styler
2146+
Instance of class with specified table attributes set.
21002147
21012148
See Also
21022149
--------
@@ -2123,6 +2170,7 @@ def export(self) -> dict[str, Any]:
21232170
Returns
21242171
-------
21252172
dict
2173+
Contains data-independent (exportable) styles applied to current Styler.
21262174
21272175
See Also
21282176
--------
@@ -2199,6 +2247,7 @@ def use(self, styles: dict[str, Any]) -> Styler:
21992247
Returns
22002248
-------
22012249
Styler
2250+
Instance of class with defined styler attributes added.
22022251
22032252
See Also
22042253
--------
@@ -2246,10 +2295,19 @@ def set_uuid(self, uuid: str) -> Styler:
22462295
Parameters
22472296
----------
22482297
uuid : str
2298+
The uuid to be applied to ``id`` attributes of HTML elements.
22492299
22502300
Returns
22512301
-------
22522302
Styler
2303+
Instance of class with specified uuid for `id` attributes set.
2304+
2305+
See Also
2306+
--------
2307+
Styler.set_caption : Set the text added to a ``<caption>`` HTML element.
2308+
Styler.set_td_classes : Set the ``class`` attribute of ``<td>`` HTML elements.
2309+
Styler.set_tooltips : Set the DataFrame of strings on ``Styler`` generating
2310+
``:hover`` tooltips.
22532311
22542312
Notes
22552313
-----
@@ -2290,6 +2348,14 @@ def set_caption(self, caption: str | tuple | list) -> Styler:
22902348
Returns
22912349
-------
22922350
Styler
2351+
Instance of class with text set for ``<caption>`` HTML element.
2352+
2353+
See Also
2354+
--------
2355+
Styler.set_td_classes : Set the ``class`` attribute of ``<td>`` HTML elements.
2356+
Styler.set_tooltips : Set the DataFrame of strings on ``Styler`` generating
2357+
``:hover`` tooltips.
2358+
Styler.set_uuid : Set the uuid applied to ``id`` attributes of HTML elements.
22932359
22942360
Examples
22952361
--------
@@ -2336,6 +2402,13 @@ def set_sticky(
23362402
Returns
23372403
-------
23382404
Styler
2405+
Instance of class with CSS set for permanently displaying headers
2406+
in scrolling frame.
2407+
2408+
See Also
2409+
--------
2410+
Styler.set_properties : Set defined CSS-properties to each ``<td>``
2411+
HTML element for the given subset.
23392412
23402413
Notes
23412414
-----
@@ -2496,6 +2569,7 @@ def set_table_styles(
24962569
Returns
24972570
-------
24982571
Styler
2572+
Instance of class with specified table styles set.
24992573
25002574
See Also
25012575
--------
@@ -2627,6 +2701,13 @@ def hide(
26272701
Returns
26282702
-------
26292703
Styler
2704+
Instance of class with specified headers/rows/columns hidden from display.
2705+
2706+
See Also
2707+
--------
2708+
Styler.apply : Apply a CSS-styling function column-wise, row-wise,
2709+
or table-wise.
2710+
Styler.map : Apply a CSS-styling function elementwise.
26302711
26312712
Notes
26322713
-----
@@ -2865,6 +2946,7 @@ def background_gradient(
28652946
Returns
28662947
-------
28672948
Styler
2949+
Instance of class with {name} colored in gradient style.
28682950
28692951
See Also
28702952
--------
@@ -3002,6 +3084,13 @@ def set_properties(self, subset: Subset | None = None, **kwargs) -> Styler:
30023084
Returns
30033085
-------
30043086
Styler
3087+
Instance of class with CSS-properties set for each ``<td>`` HTML element
3088+
in the given subset
3089+
3090+
See Also
3091+
--------
3092+
Styler.set_sticky : Add CSS to permanently display the index or column
3093+
headers in a scrolling frame.
30053094
30063095
Notes
30073096
-----
@@ -3099,6 +3188,13 @@ def bar(
30993188
Returns
31003189
-------
31013190
Styler
3191+
Contains list-like attribute with bar chart data as formatted CSS.
3192+
3193+
See Also
3194+
--------
3195+
PlotAccessor.bar : Vertical bar plot.
3196+
PlotAccessor.line : Plot Series or DataFrame as lines.
3197+
PlotAccessor.pie : Generate a pie plot.
31023198
31033199
Notes
31043200
-----
@@ -3177,6 +3273,7 @@ def highlight_null(
31773273
Returns
31783274
-------
31793275
Styler
3276+
Instance of class where null values are highlighted with given style.
31803277
31813278
See Also
31823279
--------
@@ -3231,6 +3328,7 @@ def highlight_max(
32313328
Returns
32323329
-------
32333330
Styler
3331+
Instance of class where max value is highlighted in given style.
32343332
32353333
See Also
32363334
--------
@@ -3287,6 +3385,7 @@ def highlight_min(
32873385
Returns
32883386
-------
32893387
Styler
3388+
Instance of class where min value is highlighted in given style.
32903389
32913390
See Also
32923391
--------
@@ -3351,6 +3450,7 @@ def highlight_between(
33513450
Returns
33523451
-------
33533452
Styler
3453+
Instance of class with range highlighted in given style.
33543454
33553455
See Also
33563456
--------
@@ -3471,6 +3571,7 @@ def highlight_quantile(
34713571
Returns
34723572
-------
34733573
Styler
3574+
Instance of class where values in quantile highlighted with given style.
34743575
34753576
See Also
34763577
--------
@@ -3576,6 +3677,11 @@ def from_custom_template(
35763677
Has the correct ``env``,``template_html``, ``template_html_table`` and
35773678
``template_html_style`` class attributes set.
35783679
3680+
See Also
3681+
--------
3682+
Styler.export : Export the styles applied to the current Styler.
3683+
Styler.use : Set the styles on the current Styler.
3684+
35793685
Examples
35803686
--------
35813687
>>> from pandas.io.formats.style import Styler

0 commit comments

Comments
 (0)