diff --git a/ci/code_checks.sh b/ci/code_checks.sh index 99bd90750b676..3effa667850b7 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -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 \ @@ -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 \ @@ -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 \ @@ -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 \ diff --git a/pandas/core/frame.py b/pandas/core/frame.py index 7bd2a1abf2cf0..19564afc41b49 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -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 @@ -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 diff --git a/pandas/core/generic.py b/pandas/core/generic.py index c8cd76fba2cfb..b8a0c316371d2 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -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 diff --git a/pandas/core/groupby/groupby.py b/pandas/core/groupby/groupby.py index 5928c32e22b7f..bdab641719ded 100644 --- a/pandas/core/groupby/groupby.py +++ b/pandas/core/groupby/groupby.py @@ -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) diff --git a/pandas/core/series.py b/pandas/core/series.py index 540a770b1c897..369fd4449ee73 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -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)