From bd76ea8699ff019aa0ab3caeec9b017f3c279fc1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dea=20Mar=C3=ADa=20L=C3=A9on?= Date: Tue, 13 Jun 2023 10:23:05 +0200 Subject: [PATCH 1/4] SeriesGroupBy.fillna example added --- pandas/core/groupby/generic.py | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/pandas/core/groupby/generic.py b/pandas/core/groupby/generic.py index eef3de3e61f29..7138996da07f3 100644 --- a/pandas/core/groupby/generic.py +++ b/pandas/core/groupby/generic.py @@ -908,6 +908,25 @@ def fillna( -------- ffill : Forward fill values within a group. bfill : Backward fill values within a group. + + Examples + -------- + For SeriesGroupBy: + + >>> lst = ['a', 'a', 'b', 'b'] + >>> ser = pd.Series([1, np.nan, 3, np.nan], index=lst) + >>> ser + a 1.0 + a NaN + b 3.0 + b NaN + dtype: float64 + >>> ser.groupby(level=0).fillna(value=0) + a 1.0 + a 0.0 + b 3.0 + b 0.0 + dtype: float64 """ result = self._op_via_apply( "fillna", From 0cd1d0375bb9e4d51a9280c43c47414fa042246a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dea=20Mar=C3=ADa=20L=C3=A9on?= Date: Tue, 13 Jun 2023 14:53:21 +0200 Subject: [PATCH 2/4] Added examples --- ci/code_checks.sh | 11 ----- pandas/_libs/tslibs/timedeltas.pyx | 76 +++++++++++++++++++++++++++++- pandas/core/arrays/datetimes.py | 8 ++++ 3 files changed, 83 insertions(+), 12 deletions(-) diff --git a/ci/code_checks.sh b/ci/code_checks.sh index adda422296396..f63cc1fcc5767 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -119,16 +119,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then pandas.Timestamp.utcoffset \ pandas.Timestamp.utctimetuple \ pandas.Timestamp.weekday \ - pandas.arrays.DatetimeArray \ - pandas.Timedelta.view \ - pandas.Timedelta.as_unit \ - pandas.Timedelta.ceil \ - pandas.Timedelta.floor \ - pandas.Timedelta.round \ - pandas.Timedelta.to_pytimedelta \ - pandas.Timedelta.to_timedelta64 \ - pandas.Timedelta.to_numpy \ - pandas.Timedelta.total_seconds \ pandas.arrays.TimedeltaArray \ pandas.Period.asfreq \ pandas.Period.now \ @@ -261,7 +251,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then pandas.core.window.ewm.ExponentialMovingWindow.cov \ pandas.api.indexers.BaseIndexer \ pandas.api.indexers.VariableOffsetWindowIndexer \ - pandas.core.groupby.SeriesGroupBy.fillna \ pandas.io.formats.style.Styler \ pandas.io.formats.style.Styler.from_custom_template \ pandas.io.formats.style.Styler.set_caption \ diff --git a/pandas/_libs/tslibs/timedeltas.pyx b/pandas/_libs/tslibs/timedeltas.pyx index 047b5e861da2c..e68b8b210437a 100644 --- a/pandas/_libs/tslibs/timedeltas.pyx +++ b/pandas/_libs/tslibs/timedeltas.pyx @@ -1112,7 +1112,17 @@ cdef class _Timedelta(timedelta): return self._ms * 1000 + self._us def total_seconds(self) -> float: - """Total seconds in the duration.""" + """ + Total seconds in the duration. + + Examples + -------- + >>> td = pd.Timedelta('1min') + >>> td + Timedelta('0 days 00:01:00') + >>> td.total_seconds() + 60.0 + """ # We need to override bc we overrode days/seconds/microseconds # TODO: add nanos/1e9? return self.days * 24 * 3600 + self.seconds + self.microseconds / 1_000_000 @@ -1274,6 +1284,14 @@ cdef class _Timedelta(timedelta): Notes ----- Any nanosecond resolution will be lost. + + Examples + -------- + >>> td = pd.Timedelta('3D') + >>> td + Timedelta('3 days 00:00:00') + >>> td.to_pytimedelta() + datetime.timedelta(days=3) """ if self._creso == NPY_FR_ns: return timedelta(microseconds=int(self._value) / 1000) @@ -1287,6 +1305,14 @@ cdef class _Timedelta(timedelta): def to_timedelta64(self) -> np.timedelta64: """ Return a numpy.timedelta64 object with 'ns' precision. + + Examples + -------- + >>> td = pd.Timedelta('3D') + >>> td + Timedelta('3 days 00:00:00') + >>> td.to_timedelta64() + numpy.timedelta64(259200000000000,'ns') """ cdef: str abbrev = npy_unit_to_abbrev(self._creso) @@ -1309,6 +1335,14 @@ cdef class _Timedelta(timedelta): See Also -------- Series.to_numpy : Similar method for Series. + + Examples + -------- + >>> td = pd.Timedelta('3D') + >>> td + Timedelta('3 days 00:00:00') + >>> td.to_numpy() + numpy.timedelta64(259200000000000,'ns') """ if dtype is not None or copy is not False: raise ValueError( @@ -1324,6 +1358,14 @@ cdef class _Timedelta(timedelta): ---------- dtype : str or dtype The dtype to view the underlying data as. + + Examples + -------- + >>> td = pd.Timedelta('3D') + >>> td + Timedelta('3 days 00:00:00') + >>> td.view(int) + 259200000000000 """ return np.timedelta64(self._value).view(dtype) @@ -1603,6 +1645,14 @@ cdef class _Timedelta(timedelta): Returns ------- Timedelta + + Examples + -------- + >>> td = pd.Timedelta('1001ms') + >>> td + Timedelta('0 days 00:00:01.001000') + >>> td.as_unit('s') + Timedelta('0 days 00:00:01') """ dtype = np.dtype(f"m8[{unit}]") reso = get_unit_from_dtype(dtype) @@ -1875,6 +1925,14 @@ class Timedelta(_Timedelta): Raises ------ ValueError if the freq cannot be converted + + Examples + -------- + >>> td = pd.Timedelta('1001ms') + >>> td + Timedelta('0 days 00:00:01.001000') + >>> td.round('s') + Timedelta('0 days 00:00:01') """ return self._round(freq, RoundTo.NEAREST_HALF_EVEN) @@ -1886,6 +1944,14 @@ class Timedelta(_Timedelta): ---------- freq : str Frequency string indicating the flooring resolution. + + Examples + -------- + >>> td = pd.Timedelta('1001ms') + >>> td + Timedelta('0 days 00:00:01.001000') + >>> td.floor('s') + Timedelta('0 days 00:00:01') """ return self._round(freq, RoundTo.MINUS_INFTY) @@ -1897,6 +1963,14 @@ class Timedelta(_Timedelta): ---------- freq : str Frequency string indicating the ceiling resolution. + + Examples + -------- + >>> td = pd.Timedelta('1001ms') + >>> td + Timedelta('0 days 00:00:01.001000') + >>> td.ceil('s') + Timedelta('0 days 00:00:02') """ return self._round(freq, RoundTo.PLUS_INFTY) diff --git a/pandas/core/arrays/datetimes.py b/pandas/core/arrays/datetimes.py index 3d083e55b12ab..d6afba8c34904 100644 --- a/pandas/core/arrays/datetimes.py +++ b/pandas/core/arrays/datetimes.py @@ -183,6 +183,14 @@ class DatetimeArray(dtl.TimelikeOps, dtl.DatelikeOps): # type: ignore[misc] Methods ------- None + + Examples + -------- + >>> pd.arrays.DatetimeArray(pd.DatetimeIndex(['2023-01-01', '2023-01-02']), + ... freq='D') + + ['2023-01-01 00:00:00', '2023-01-02 00:00:00'] + Length: 2, dtype: datetime64[ns] """ _typ = "datetimearray" From 4167ccab60a0e1eca69a1b7a8b10a274a20347e0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dea=20Mar=C3=ADa=20L=C3=A9on?= Date: Wed, 14 Jun 2023 10:41:11 +0200 Subject: [PATCH 3/4] Corrected failing test for timedelta.total_seconds --- pandas/_libs/tslibs/nattype.pyx | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/pandas/_libs/tslibs/nattype.pyx b/pandas/_libs/tslibs/nattype.pyx index ea859a5f7d53d..75205a359db68 100644 --- a/pandas/_libs/tslibs/nattype.pyx +++ b/pandas/_libs/tslibs/nattype.pyx @@ -4,7 +4,6 @@ from cpython.datetime cimport ( PyDelta_Check, datetime, import_datetime, - timedelta, ) import_datetime() @@ -440,7 +439,20 @@ class NaTType(_NaT): Monday == 1 ... Sunday == 7. """, ) - total_seconds = _make_nan_func("total_seconds", timedelta.total_seconds.__doc__) + total_seconds = _make_nan_func( + "total_seconds", + """ + Total seconds in the duration. + + Examples + -------- + >>> td = pd.Timedelta('1min') + >>> td + Timedelta('0 days 00:01:00') + >>> td.total_seconds() + 60.0 + """, + ) month_name = _make_nan_func( "month_name", """ From 7ba6993fa1406785bc2724ca4bf805929401b39f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dea=20Mar=C3=ADa=20L=C3=A9on?= Date: Wed, 14 Jun 2023 19:18:54 +0200 Subject: [PATCH 4/4] Corrected fillna example --- pandas/core/groupby/generic.py | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/pandas/core/groupby/generic.py b/pandas/core/groupby/generic.py index 94938fea32862..cecb9a84c62dd 100644 --- a/pandas/core/groupby/generic.py +++ b/pandas/core/groupby/generic.py @@ -919,19 +919,21 @@ def fillna( -------- For SeriesGroupBy: - >>> lst = ['a', 'a', 'b', 'b'] - >>> ser = pd.Series([1, np.nan, 3, np.nan], index=lst) + >>> lst = ['cat', 'cat', 'cat', 'mouse', 'mouse'] + >>> ser = pd.Series([1, None, None, 2, None], index=lst) >>> ser - a 1.0 - a NaN - b 3.0 - b NaN + cat 1.0 + cat NaN + cat NaN + mouse 2.0 + mouse NaN dtype: float64 - >>> ser.groupby(level=0).fillna(value=0) - a 1.0 - a 0.0 - b 3.0 - b 0.0 + >>> ser.groupby(level=0).fillna(0, limit=1) + cat 1.0 + cat 0.0 + cat NaN + mouse 2.0 + mouse 0.0 dtype: float64 """ result = self._op_via_apply(