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/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", """ 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" diff --git a/pandas/core/groupby/generic.py b/pandas/core/groupby/generic.py index 2b1ff05f18d5e..cecb9a84c62dd 100644 --- a/pandas/core/groupby/generic.py +++ b/pandas/core/groupby/generic.py @@ -914,6 +914,27 @@ def fillna( -------- ffill : Forward fill values within a group. bfill : Backward fill values within a group. + + Examples + -------- + For SeriesGroupBy: + + >>> lst = ['cat', 'cat', 'cat', 'mouse', 'mouse'] + >>> ser = pd.Series([1, None, None, 2, None], index=lst) + >>> ser + cat 1.0 + cat NaN + cat NaN + mouse 2.0 + mouse NaN + dtype: float64 + >>> 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( "fillna",