Skip to content

Commit

Permalink
DOC: Fixing EX01 - added examples (#53240)
Browse files Browse the repository at this point in the history 
DOC Examples bfill, argsort, iterrows
  • Loading branch information
@DeaMariaLeon
DeaMariaLeon authored May 15, 2023
1 parent 2b107bf commit 489f15e
Show file tree
Hide file tree
Showing 5 changed files with 125 additions and 19 deletions.
7 changes: 0 additions & 7 deletions ci/code_checks.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -81,10 +81,8 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
MSG='Partially validate docstrings (EX01)' ; echo $MSG
$BASE_DIR/scripts/validate_docstrings.py --format=actions --errors=EX01 --ignore_functions \
pandas.Series.backfill \
pandas.Series.bfill \
pandas.Series.ffill \
pandas.Series.pad \
pandas.Series.argsort \
pandas.Series.reorder_levels \
pandas.Series.ravel \
pandas.Series.first_valid_index \
Expand Down Expand Up @@ -424,7 +422,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
pandas.core.groupby.SeriesGroupBy.get_group \
pandas.core.groupby.DataFrameGroupBy.all \
pandas.core.groupby.DataFrameGroupBy.any \
pandas.core.groupby.DataFrameGroupBy.bfill \
pandas.core.groupby.DataFrameGroupBy.count \
pandas.core.groupby.DataFrameGroupBy.cummax \
pandas.core.groupby.DataFrameGroupBy.cummin \
Expand All @@ -447,7 +444,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
pandas.core.groupby.DataFrameGroupBy.var \
pandas.core.groupby.SeriesGroupBy.all \
pandas.core.groupby.SeriesGroupBy.any \
pandas.core.groupby.SeriesGroupBy.bfill \
pandas.core.groupby.SeriesGroupBy.count \
pandas.core.groupby.SeriesGroupBy.cummax \
pandas.core.groupby.SeriesGroupBy.cummin \
Expand Down Expand Up @@ -517,10 +513,7 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
pandas.api.extensions.ExtensionArray.shape \
pandas.api.extensions.ExtensionArray.tolist \
pandas.DataFrame.columns \
pandas.DataFrame.iterrows \
pandas.DataFrame.pipe \
pandas.DataFrame.backfill \
pandas.DataFrame.bfill \
pandas.DataFrame.ffill \
pandas.DataFrame.pad \
pandas.DataFrame.swapaxes \
Expand Down
27 changes: 15 additions & 12 deletions pandas/core/frame.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1373,18 +1373,7 @@ def iterrows(self) -> Iterable[tuple[Hashable, Series]]:
-----
1. Because ``iterrows`` returns a Series for each row,
it does **not** preserve dtypes across the rows (dtypes are
preserved across columns for DataFrames). For example,
>>> df = pd.DataFrame([[1, 1.5]], columns=['int', 'float'])
>>> row = next(df.iterrows())[1]
>>> row
int 1.0
float 1.5
Name: 0, dtype: float64
>>> print(row['int'].dtype)
float64
>>> print(df['int'].dtype)
int64
preserved across columns for DataFrames).
To preserve dtypes while iterating over the rows, it is better
to use :meth:`itertuples` which returns namedtuples of the values
Expand All @@ -1394,6 +1383,20 @@ def iterrows(self) -> Iterable[tuple[Hashable, Series]]:
This is not guaranteed to work in all cases. Depending on the
data types, the iterator returns a copy and not a view, and writing
to it will have no effect.
Examples
--------
>>> df = pd.DataFrame([[1, 1.5]], columns=['int', 'float'])
>>> row = next(df.iterrows())[1]
>>> row
int 1.0
float 1.5
Name: 0, dtype: float64
>>> print(row['int'].dtype)
float64
>>> print(df['int'].dtype)
int64
"""
columns = self.columns
klass = self._constructor_sliced
Expand Down
46 changes: 46 additions & 0 deletions pandas/core/generic.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7262,6 +7262,52 @@ def bfill(
-------
{klass} or None
Object with missing values filled or None if ``inplace=True``.
Examples
--------
For Series:
>>> s = pd.Series([1, None, None, 2])
>>> s.bfill()
0 1.0
1 2.0
2 2.0
3 2.0
dtype: float64
>>> s.bfill(downcast='infer')
0 1
1 2
2 2
3 2
dtype: int64
>>> s.bfill(limit=1)
0 1.0
1 NaN
2 2.0
3 2.0
dtype: float64
With DataFrame:
>>> df = pd.DataFrame({{'A': [1, None, None, 4], 'B': [None, 5, None, 7]}})
>>> df
A B
0 1.0 NaN
1 NaN 5.0
2 NaN NaN
3 4.0 7.0
>>> df.bfill()
A B
0 1.0 5.0
1 4.0 5.0
2 4.0 7.0
3 4.0 7.0
>>> df.bfill(downcast='infer', limit=1)
A B
0 1.0 5
1 NaN 5
2 4.0 7
3 4.0 7
"""
return self.fillna(
method="bfill", axis=axis, inplace=inplace, limit=limit, downcast=downcast
Expand Down
55 changes: 55 additions & 0 deletions pandas/core/groupby/groupby.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3019,6 +3019,61 @@ def bfill(self, limit: int | None = None):
DataFrame.bfill: Backward fill the missing values in the dataset.
Series.fillna: Fill NaN values of a Series.
DataFrame.fillna: Fill NaN values of a DataFrame.
Examples
--------
With Series:
>>> index = ['Falcon', 'Falcon', 'Parrot', 'Parrot', 'Parrot']
>>> s = pd.Series([None, 1, None, None, 3], index=index)
>>> s
Falcon NaN
Falcon 1.0
Parrot NaN
Parrot NaN
Parrot 3.0
dtype: float64
>>> s.groupby(level=0).bfill()
Falcon 1.0
Falcon 1.0
Parrot 3.0
Parrot 3.0
Parrot 3.0
dtype: float64
>>> s.groupby(level=0).bfill(limit=1)
Falcon 1.0
Falcon 1.0
Parrot NaN
Parrot 3.0
Parrot 3.0
dtype: float64
With DataFrame:
>>> df = pd.DataFrame({'A': [1, None, None, None, 4],
... 'B': [None, None, 5, None, 7]}, index=index)
>>> df
A B
Falcon 1.0 NaN
Falcon NaN NaN
Parrot NaN 5.0
Parrot NaN NaN
Parrot 4.0 7.0
>>> df.groupby(level=0).bfill()
A B
Falcon 1.0 NaN
Falcon NaN NaN
Parrot 4.0 5.0
Parrot 4.0 7.0
Parrot 4.0 7.0
>>> df.groupby(level=0).bfill(limit=1)
A B
Falcon 1.0 NaN
Falcon NaN NaN
Parrot NaN 5.0
Parrot 4.0 7.0
Parrot 4.0 7.0
"""
return self._fill("bfill", limit=limit)

Expand Down
9 changes: 9 additions & 0 deletions pandas/core/series.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3811,6 +3811,15 @@ def argsort(
See Also
--------
numpy.ndarray.argsort : Returns the indices that would sort this array.
Examples
--------
>>> s = pd.Series([3, 2, 1])
>>> s.argsort()
0 2
1 1
2 0
dtype: int64
"""
values = self._values
mask = isna(values)
Expand Down

0 comments on commit 489f15e

Please sign in to comment.