Skip to content

Commit 489f15e

Browse files
DeaMariaLeonDeaMariaLeon
authored
DOC: Fixing EX01 - added examples (#53240)
DOC Examples bfill, argsort, iterrows
1 parent 2b107bf commit 489f15e

File tree

5 files changed

+125
-19
lines changed

5 files changed

+125
-19
lines changed

‎ci/code_checks.sh

-7
Original file line numberDiff line numberDiff line change
@@ -81,10 +81,8 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
8181
MSG='Partially validate docstrings (EX01)' ; echo $MSG
8282
$BASE_DIR/scripts/validate_docstrings.py --format=actions --errors=EX01 --ignore_functions \
8383
pandas.Series.backfill \
84-
pandas.Series.bfill \
8584
pandas.Series.ffill \
8685
pandas.Series.pad \
87-
pandas.Series.argsort \
8886
pandas.Series.reorder_levels \
8987
pandas.Series.ravel \
9088
pandas.Series.first_valid_index \
@@ -424,7 +422,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
424422
pandas.core.groupby.SeriesGroupBy.get_group \
425423
pandas.core.groupby.DataFrameGroupBy.all \
426424
pandas.core.groupby.DataFrameGroupBy.any \
427-
pandas.core.groupby.DataFrameGroupBy.bfill \
428425
pandas.core.groupby.DataFrameGroupBy.count \
429426
pandas.core.groupby.DataFrameGroupBy.cummax \
430427
pandas.core.groupby.DataFrameGroupBy.cummin \
@@ -447,7 +444,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
447444
pandas.core.groupby.DataFrameGroupBy.var \
448445
pandas.core.groupby.SeriesGroupBy.all \
449446
pandas.core.groupby.SeriesGroupBy.any \
450-
pandas.core.groupby.SeriesGroupBy.bfill \
451447
pandas.core.groupby.SeriesGroupBy.count \
452448
pandas.core.groupby.SeriesGroupBy.cummax \
453449
pandas.core.groupby.SeriesGroupBy.cummin \
@@ -517,10 +513,7 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
517513
pandas.api.extensions.ExtensionArray.shape \
518514
pandas.api.extensions.ExtensionArray.tolist \
519515
pandas.DataFrame.columns \
520-
pandas.DataFrame.iterrows \
521-
pandas.DataFrame.pipe \
522516
pandas.DataFrame.backfill \
523-
pandas.DataFrame.bfill \
524517
pandas.DataFrame.ffill \
525518
pandas.DataFrame.pad \
526519
pandas.DataFrame.swapaxes \

‎pandas/core/frame.py

+15-12
Original file line numberDiff line numberDiff line change
@@ -1373,18 +1373,7 @@ def iterrows(self) -> Iterable[tuple[Hashable, Series]]:
13731373
-----
13741374
1. Because ``iterrows`` returns a Series for each row,
13751375
it does **not** preserve dtypes across the rows (dtypes are
1376-
preserved across columns for DataFrames). For example,
1377-
1378-
>>> df = pd.DataFrame([[1, 1.5]], columns=['int', 'float'])
1379-
>>> row = next(df.iterrows())[1]
1380-
>>> row
1381-
int 1.0
1382-
float 1.5
1383-
Name: 0, dtype: float64
1384-
>>> print(row['int'].dtype)
1385-
float64
1386-
>>> print(df['int'].dtype)
1387-
int64
1376+
preserved across columns for DataFrames).
13881377
13891378
To preserve dtypes while iterating over the rows, it is better
13901379
to use :meth:`itertuples` which returns namedtuples of the values
@@ -1394,6 +1383,20 @@ def iterrows(self) -> Iterable[tuple[Hashable, Series]]:
13941383
This is not guaranteed to work in all cases. Depending on the
13951384
data types, the iterator returns a copy and not a view, and writing
13961385
to it will have no effect.
1386+
1387+
Examples
1388+
--------
1389+
1390+
>>> df = pd.DataFrame([[1, 1.5]], columns=['int', 'float'])
1391+
>>> row = next(df.iterrows())[1]
1392+
>>> row
1393+
int 1.0
1394+
float 1.5
1395+
Name: 0, dtype: float64
1396+
>>> print(row['int'].dtype)
1397+
float64
1398+
>>> print(df['int'].dtype)
1399+
int64
13971400
"""
13981401
columns = self.columns
13991402
klass = self._constructor_sliced

‎pandas/core/generic.py

+46
Original file line numberDiff line numberDiff line change
@@ -7262,6 +7262,52 @@ def bfill(
72627262
-------
72637263
{klass} or None
72647264
Object with missing values filled or None if ``inplace=True``.
7265+
7266+
Examples
7267+
--------
7268+
For Series:
7269+
7270+
>>> s = pd.Series([1, None, None, 2])
7271+
>>> s.bfill()
7272+
0 1.0
7273+
1 2.0
7274+
2 2.0
7275+
3 2.0
7276+
dtype: float64
7277+
>>> s.bfill(downcast='infer')
7278+
0 1
7279+
1 2
7280+
2 2
7281+
3 2
7282+
dtype: int64
7283+
>>> s.bfill(limit=1)
7284+
0 1.0
7285+
1 NaN
7286+
2 2.0
7287+
3 2.0
7288+
dtype: float64
7289+
7290+
With DataFrame:
7291+
7292+
>>> df = pd.DataFrame({{'A': [1, None, None, 4], 'B': [None, 5, None, 7]}})
7293+
>>> df
7294+
A B
7295+
0 1.0 NaN
7296+
1 NaN 5.0
7297+
2 NaN NaN
7298+
3 4.0 7.0
7299+
>>> df.bfill()
7300+
A B
7301+
0 1.0 5.0
7302+
1 4.0 5.0
7303+
2 4.0 7.0
7304+
3 4.0 7.0
7305+
>>> df.bfill(downcast='infer', limit=1)
7306+
A B
7307+
0 1.0 5
7308+
1 NaN 5
7309+
2 4.0 7
7310+
3 4.0 7
72657311
"""
72667312
return self.fillna(
72677313
method="bfill", axis=axis, inplace=inplace, limit=limit, downcast=downcast

‎pandas/core/groupby/groupby.py

+55
Original file line numberDiff line numberDiff line change
@@ -3019,6 +3019,61 @@ def bfill(self, limit: int | None = None):
30193019
DataFrame.bfill: Backward fill the missing values in the dataset.
30203020
Series.fillna: Fill NaN values of a Series.
30213021
DataFrame.fillna: Fill NaN values of a DataFrame.
3022+
3023+
Examples
3024+
--------
3025+
3026+
With Series:
3027+
3028+
>>> index = ['Falcon', 'Falcon', 'Parrot', 'Parrot', 'Parrot']
3029+
>>> s = pd.Series([None, 1, None, None, 3], index=index)
3030+
>>> s
3031+
Falcon NaN
3032+
Falcon 1.0
3033+
Parrot NaN
3034+
Parrot NaN
3035+
Parrot 3.0
3036+
dtype: float64
3037+
>>> s.groupby(level=0).bfill()
3038+
Falcon 1.0
3039+
Falcon 1.0
3040+
Parrot 3.0
3041+
Parrot 3.0
3042+
Parrot 3.0
3043+
dtype: float64
3044+
>>> s.groupby(level=0).bfill(limit=1)
3045+
Falcon 1.0
3046+
Falcon 1.0
3047+
Parrot NaN
3048+
Parrot 3.0
3049+
Parrot 3.0
3050+
dtype: float64
3051+
3052+
With DataFrame:
3053+
3054+
>>> df = pd.DataFrame({'A': [1, None, None, None, 4],
3055+
... 'B': [None, None, 5, None, 7]}, index=index)
3056+
>>> df
3057+
A B
3058+
Falcon 1.0 NaN
3059+
Falcon NaN NaN
3060+
Parrot NaN 5.0
3061+
Parrot NaN NaN
3062+
Parrot 4.0 7.0
3063+
>>> df.groupby(level=0).bfill()
3064+
A B
3065+
Falcon 1.0 NaN
3066+
Falcon NaN NaN
3067+
Parrot 4.0 5.0
3068+
Parrot 4.0 7.0
3069+
Parrot 4.0 7.0
3070+
>>> df.groupby(level=0).bfill(limit=1)
3071+
A B
3072+
Falcon 1.0 NaN
3073+
Falcon NaN NaN
3074+
Parrot NaN 5.0
3075+
Parrot 4.0 7.0
3076+
Parrot 4.0 7.0
30223077
"""
30233078
return self._fill("bfill", limit=limit)
30243079

‎pandas/core/series.py

+9
Original file line numberDiff line numberDiff line change
@@ -3811,6 +3811,15 @@ def argsort(
38113811
See Also
38123812
--------
38133813
numpy.ndarray.argsort : Returns the indices that would sort this array.
3814+
3815+
Examples
3816+
--------
3817+
>>> s = pd.Series([3, 2, 1])
3818+
>>> s.argsort()
3819+
0 2
3820+
1 1
3821+
2 0
3822+
dtype: int64
38143823
"""
38153824
values = self._values
38163825
mask = isna(values)

0 commit comments

Comments
 (0)