Skip to content

Commit 841e760

Browse files
DeaMariaLeonDeaMariaLeon
authored
DOC: Fixing EX01 - Added examples (#53647)
* SeriesGroupBy.fillna example added * Added examples * Corrected failing test for timedelta.total_seconds * Corrected fillna example
1 parent 3e2e7c3 commit 841e760

File tree

5 files changed

+118
-14
lines changed

5 files changed

+118
-14
lines changed

‎ci/code_checks.sh

Lines changed: 0 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -119,16 +119,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
119119
pandas.Timestamp.utcoffset \
120120
pandas.Timestamp.utctimetuple \
121121
pandas.Timestamp.weekday \
122-
pandas.arrays.DatetimeArray \
123-
pandas.Timedelta.view \
124-
pandas.Timedelta.as_unit \
125-
pandas.Timedelta.ceil \
126-
pandas.Timedelta.floor \
127-
pandas.Timedelta.round \
128-
pandas.Timedelta.to_pytimedelta \
129-
pandas.Timedelta.to_timedelta64 \
130-
pandas.Timedelta.to_numpy \
131-
pandas.Timedelta.total_seconds \
132122
pandas.arrays.TimedeltaArray \
133123
pandas.Period.asfreq \
134124
pandas.Period.now \
@@ -261,7 +251,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
261251
pandas.core.window.ewm.ExponentialMovingWindow.cov \
262252
pandas.api.indexers.BaseIndexer \
263253
pandas.api.indexers.VariableOffsetWindowIndexer \
264-
pandas.core.groupby.SeriesGroupBy.fillna \
265254
pandas.io.formats.style.Styler \
266255
pandas.io.formats.style.Styler.from_custom_template \
267256
pandas.io.formats.style.Styler.set_caption \

‎pandas/_libs/tslibs/nattype.pyx

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,6 @@ from cpython.datetime cimport (
44
PyDelta_Check,
55
datetime,
66
import_datetime,
7-
timedelta,
87
)
98

109
import_datetime()
@@ -440,7 +439,20 @@ class NaTType(_NaT):
440439
Monday == 1 ... Sunday == 7.
441440
""",
442441
)
443-
total_seconds = _make_nan_func("total_seconds", timedelta.total_seconds.__doc__)
442+
total_seconds = _make_nan_func(
443+
"total_seconds",
444+
"""
445+
Total seconds in the duration.
446+
447+
Examples
448+
--------
449+
>>> td = pd.Timedelta('1min')
450+
>>> td
451+
Timedelta('0 days 00:01:00')
452+
>>> td.total_seconds()
453+
60.0
454+
""",
455+
)
444456
month_name = _make_nan_func(
445457
"month_name",
446458
"""

‎pandas/_libs/tslibs/timedeltas.pyx

Lines changed: 75 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1112,7 +1112,17 @@ cdef class _Timedelta(timedelta):
11121112
return self._ms * 1000 + self._us
11131113

11141114
def total_seconds(self) -> float:
1115-
"""Total seconds in the duration."""
1115+
"""
1116+
Total seconds in the duration.
1117+
1118+
Examples
1119+
--------
1120+
>>> td = pd.Timedelta('1min')
1121+
>>> td
1122+
Timedelta('0 days 00:01:00')
1123+
>>> td.total_seconds()
1124+
60.0
1125+
"""
11161126
# We need to override bc we overrode days/seconds/microseconds
11171127
# TODO: add nanos/1e9?
11181128
return self.days * 24 * 3600 + self.seconds + self.microseconds / 1_000_000
@@ -1274,6 +1284,14 @@ cdef class _Timedelta(timedelta):
12741284
Notes
12751285
-----
12761286
Any nanosecond resolution will be lost.
1287+
1288+
Examples
1289+
--------
1290+
>>> td = pd.Timedelta('3D')
1291+
>>> td
1292+
Timedelta('3 days 00:00:00')
1293+
>>> td.to_pytimedelta()
1294+
datetime.timedelta(days=3)
12771295
"""
12781296
if self._creso == NPY_FR_ns:
12791297
return timedelta(microseconds=int(self._value) / 1000)
@@ -1287,6 +1305,14 @@ cdef class _Timedelta(timedelta):
12871305
def to_timedelta64(self) -> np.timedelta64:
12881306
"""
12891307
Return a numpy.timedelta64 object with 'ns' precision.
1308+
1309+
Examples
1310+
--------
1311+
>>> td = pd.Timedelta('3D')
1312+
>>> td
1313+
Timedelta('3 days 00:00:00')
1314+
>>> td.to_timedelta64()
1315+
numpy.timedelta64(259200000000000,'ns')
12901316
"""
12911317
cdef:
12921318
str abbrev = npy_unit_to_abbrev(self._creso)
@@ -1309,6 +1335,14 @@ cdef class _Timedelta(timedelta):
13091335
See Also
13101336
--------
13111337
Series.to_numpy : Similar method for Series.
1338+
1339+
Examples
1340+
--------
1341+
>>> td = pd.Timedelta('3D')
1342+
>>> td
1343+
Timedelta('3 days 00:00:00')
1344+
>>> td.to_numpy()
1345+
numpy.timedelta64(259200000000000,'ns')
13121346
"""
13131347
if dtype is not None or copy is not False:
13141348
raise ValueError(
@@ -1324,6 +1358,14 @@ cdef class _Timedelta(timedelta):
13241358
----------
13251359
dtype : str or dtype
13261360
The dtype to view the underlying data as.
1361+
1362+
Examples
1363+
--------
1364+
>>> td = pd.Timedelta('3D')
1365+
>>> td
1366+
Timedelta('3 days 00:00:00')
1367+
>>> td.view(int)
1368+
259200000000000
13271369
"""
13281370
return np.timedelta64(self._value).view(dtype)
13291371

@@ -1603,6 +1645,14 @@ cdef class _Timedelta(timedelta):
16031645
Returns
16041646
-------
16051647
Timedelta
1648+
1649+
Examples
1650+
--------
1651+
>>> td = pd.Timedelta('1001ms')
1652+
>>> td
1653+
Timedelta('0 days 00:00:01.001000')
1654+
>>> td.as_unit('s')
1655+
Timedelta('0 days 00:00:01')
16061656
"""
16071657
dtype = np.dtype(f"m8[{unit}]")
16081658
reso = get_unit_from_dtype(dtype)
@@ -1875,6 +1925,14 @@ class Timedelta(_Timedelta):
18751925
Raises
18761926
------
18771927
ValueError if the freq cannot be converted
1928+
1929+
Examples
1930+
--------
1931+
>>> td = pd.Timedelta('1001ms')
1932+
>>> td
1933+
Timedelta('0 days 00:00:01.001000')
1934+
>>> td.round('s')
1935+
Timedelta('0 days 00:00:01')
18781936
"""
18791937
return self._round(freq, RoundTo.NEAREST_HALF_EVEN)
18801938

@@ -1886,6 +1944,14 @@ class Timedelta(_Timedelta):
18861944
----------
18871945
freq : str
18881946
Frequency string indicating the flooring resolution.
1947+
1948+
Examples
1949+
--------
1950+
>>> td = pd.Timedelta('1001ms')
1951+
>>> td
1952+
Timedelta('0 days 00:00:01.001000')
1953+
>>> td.floor('s')
1954+
Timedelta('0 days 00:00:01')
18891955
"""
18901956
return self._round(freq, RoundTo.MINUS_INFTY)
18911957

@@ -1897,6 +1963,14 @@ class Timedelta(_Timedelta):
18971963
----------
18981964
freq : str
18991965
Frequency string indicating the ceiling resolution.
1966+
1967+
Examples
1968+
--------
1969+
>>> td = pd.Timedelta('1001ms')
1970+
>>> td
1971+
Timedelta('0 days 00:00:01.001000')
1972+
>>> td.ceil('s')
1973+
Timedelta('0 days 00:00:02')
19001974
"""
19011975
return self._round(freq, RoundTo.PLUS_INFTY)
19021976

‎pandas/core/arrays/datetimes.py

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -183,6 +183,14 @@ class DatetimeArray(dtl.TimelikeOps, dtl.DatelikeOps): # type: ignore[misc]
183183
Methods
184184
-------
185185
None
186+
187+
Examples
188+
--------
189+
>>> pd.arrays.DatetimeArray(pd.DatetimeIndex(['2023-01-01', '2023-01-02']),
190+
... freq='D')
191+
<DatetimeArray>
192+
['2023-01-01 00:00:00', '2023-01-02 00:00:00']
193+
Length: 2, dtype: datetime64[ns]
186194
"""
187195

188196
_typ = "datetimearray"

‎pandas/core/groupby/generic.py

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -914,6 +914,27 @@ def fillna(
914914
--------
915915
ffill : Forward fill values within a group.
916916
bfill : Backward fill values within a group.
917+
918+
Examples
919+
--------
920+
For SeriesGroupBy:
921+
922+
>>> lst = ['cat', 'cat', 'cat', 'mouse', 'mouse']
923+
>>> ser = pd.Series([1, None, None, 2, None], index=lst)
924+
>>> ser
925+
cat 1.0
926+
cat NaN
927+
cat NaN
928+
mouse 2.0
929+
mouse NaN
930+
dtype: float64
931+
>>> ser.groupby(level=0).fillna(0, limit=1)
932+
cat 1.0
933+
cat 0.0
934+
cat NaN
935+
mouse 2.0
936+
mouse 0.0
937+
dtype: float64
917938
"""
918939
result = self._op_via_apply(
919940
"fillna",

0 commit comments

Comments
 (0)