From 4a7891fc296a5e2ee5ff4dca60d9e5a49f5839d1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dea=20Mar=C3=ADa=20L=C3=A9on?= Date: Tue, 16 May 2023 20:15:42 +0200 Subject: [PATCH 1/3] Added examples --- ci/code_checks.sh | 10 ---- pandas/_libs/tslibs/period.pyx | 15 ++++++ pandas/core/arrays/datetimes.py | 89 +++++++++++++++++++++++++++++++++ pandas/core/arrays/period.py | 15 ++++++ 4 files changed, 119 insertions(+), 10 deletions(-) diff --git a/ci/code_checks.sh b/ci/code_checks.sh index 3effa667850b7..ffc3ab166858f 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -87,16 +87,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then pandas.Series.ravel \ pandas.Series.first_valid_index \ pandas.Series.last_valid_index \ - pandas.Series.dt.date \ - pandas.Series.dt.time \ - pandas.Series.dt.timetz \ - pandas.Series.dt.dayofyear \ - pandas.Series.dt.day_of_year \ - pandas.Series.dt.quarter \ - pandas.Series.dt.daysinmonth \ - pandas.Series.dt.days_in_month \ - pandas.Series.dt.tz \ - pandas.Series.dt.end_time \ pandas.Series.dt.days \ pandas.Series.dt.seconds \ pandas.Series.dt.microseconds \ diff --git a/pandas/_libs/tslibs/period.pyx b/pandas/_libs/tslibs/period.pyx index 7f54765ddbab5..9f0e6963d2cc3 100644 --- a/pandas/_libs/tslibs/period.pyx +++ b/pandas/_libs/tslibs/period.pyx @@ -1661,6 +1661,21 @@ cdef class PeriodMixin: Period.dayofyear : Return the day of year. Period.daysinmonth : Return the days in that month. Period.dayofweek : Return the day of the week. + + Examples + -------- + >>> period = pd.period_range('2020-1-1 00:00', '2020-3-1 00:00', freq='M') + >>> s = pd.Series(period) + >>> s + 0 2020-01 + 1 2020-02 + 2 2020-03 + dtype: period[M] + >>> s.dt.end_time + 0 2020-01-31 23:59:59.999999999 + 1 2020-02-29 23:59:59.999999999 + 2 2020-03-31 23:59:59.999999999 + dtype: datetime64[ns] """ return self.to_timestamp(how="end") diff --git a/pandas/core/arrays/datetimes.py b/pandas/core/arrays/datetimes.py index 9ba3067be5a14..a8c3580217957 100644 --- a/pandas/core/arrays/datetimes.py +++ b/pandas/core/arrays/datetimes.py @@ -564,6 +564,17 @@ def tz(self) -> tzinfo | None: ------- datetime.tzinfo, pytz.tzinfo.BaseTZInfo, dateutil.tz.tz.tzfile, or None Returns None when the array is tz-naive. + + Examples + -------- + >>> s = pd.Series(["1/1/2020 10:00:00+00:00", "2/1/2020 11:00:00+00:00"]) + >>> s = pd.to_datetime(s) + >>> s + 0 2020-01-01 10:00:00+00:00 + 1 2020-02-01 11:00:00+00:00 + dtype: datetime64[ns, UTC] + >>> s.dt.tz + datetime.timezone.utc """ # GH 18595 return getattr(self.dtype, "tz", None) @@ -1312,6 +1323,19 @@ def time(self) -> npt.NDArray[np.object_]: Returns numpy array of :class:`datetime.time` objects. The time part of the Timestamps. + + Examples + -------- + >>> s = pd.Series(["1/1/2020 10:00:00+00:00", "2/1/2020 11:00:00+00:00"]) + >>> s = pd.to_datetime(s) + >>> s + 0 2020-01-01 10:00:00+00:00 + 1 2020-02-01 11:00:00+00:00 + dtype: datetime64[ns, UTC] + >>> s.dt.time + 0 10:00:00 + 1 11:00:00 + dtype: object """ # If the Timestamps have a timezone that is not UTC, # convert them into their i8 representation while @@ -1326,6 +1350,19 @@ def timetz(self) -> npt.NDArray[np.object_]: Returns numpy array of :class:`datetime.time` objects with timezones. The time part of the Timestamps. + + Examples + -------- + >>> s = pd.Series(["1/1/2020 10:00:00+00:00", "2/1/2020 11:00:00+00:00"]) + >>> s = pd.to_datetime(s) + >>> s + 0 2020-01-01 10:00:00+00:00 + 1 2020-02-01 11:00:00+00:00 + dtype: datetime64[ns, UTC] + >>> s.dt.timetz + 0 10:00:00+00:00 + 1 11:00:00+00:00 + dtype: object """ return ints_to_pydatetime(self.asi8, self.tz, box="time", reso=self._creso) @@ -1336,6 +1373,19 @@ def date(self) -> npt.NDArray[np.object_]: Namely, the date part of Timestamps without time and timezone information. + + Examples + -------- + >>> s = pd.Series(["1/1/2020 10:00:00+00:00", "2/1/2020 11:00:00+00:00"]) + >>> s = pd.to_datetime(s) + >>> s + 0 2020-01-01 10:00:00+00:00 + 1 2020-02-01 11:00:00+00:00 + dtype: datetime64[ns, UTC] + >>> s.dt.date + 0 2020-01-01 + 1 2020-02-01 + dtype: object """ # If the Timestamps have a timezone that is not UTC, # convert them into their i8 representation while @@ -1614,6 +1664,19 @@ def isocalendar(self) -> DataFrame: "doy", """ The ordinal day of the year. + + Examples + -------- + >>> s = pd.Series(["1/1/2020 10:00:00+00:00", "2/1/2020 11:00:00+00:00"]) + >>> s = pd.to_datetime(s) + >>> s + 0 2020-01-01 10:00:00+00:00 + 1 2020-02-01 11:00:00+00:00 + dtype: datetime64[ns, UTC] + >>> s.dt.dayofyear + 0 1 + 1 32 + dtype: int32 """, ) dayofyear = day_of_year @@ -1622,6 +1685,19 @@ def isocalendar(self) -> DataFrame: "q", """ The quarter of the date. + + Examples + -------- + >>> s = pd.Series(["1/1/2020 10:00:00+00:00", "4/1/2020 11:00:00+00:00"]) + >>> s = pd.to_datetime(s) + >>> s + 0 2020-01-01 10:00:00+00:00 + 1 2020-04-01 11:00:00+00:00 + dtype: datetime64[ns, UTC] + >>> s.dt.quarter + 0 1 + 1 2 + dtype: int32 """, ) days_in_month = _field_accessor( @@ -1629,6 +1705,19 @@ def isocalendar(self) -> DataFrame: "dim", """ The number of days in the month. + + Examples + -------- + >>> s = pd.Series(["1/1/2020 10:00:00+00:00", "2/1/2020 11:00:00+00:00"]) + >>> s = pd.to_datetime(s) + >>> s + 0 2020-01-01 10:00:00+00:00 + 1 2020-02-01 11:00:00+00:00 + dtype: datetime64[ns, UTC] + >>> s.dt.daysinmonth + 0 31 + 1 29 + dtype: int32 """, ) daysinmonth = days_in_month diff --git a/pandas/core/arrays/period.py b/pandas/core/arrays/period.py index 854f7f92cce32..237ac99bcf45f 100644 --- a/pandas/core/arrays/period.py +++ b/pandas/core/arrays/period.py @@ -483,6 +483,21 @@ def __arrow_array__(self, type=None): "days_in_month", """ The number of days in the month. + + Examples + -------- + >>> period = pd.period_range('2020-1-1 00:00', '2020-3-1 00:00', freq='M') + >>> s = pd.Series(period) + >>> s + 0 2020-01 + 1 2020-02 + 2 2020-03 + dtype: period[M] + >>> s.dt.days_in_month + 0 31 + 1 29 + 2 31 + dtype: int64 """, ) daysinmonth = days_in_month From 1ff9704e6721220c9ed37fdcd574ec55bb9f220a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dea=20Mar=C3=ADa=20L=C3=A9on?= Date: Wed, 17 May 2023 12:14:45 +0200 Subject: [PATCH 2/3] Changed end_time example --- pandas/_libs/tslibs/period.pyx | 14 ++------------ 1 file changed, 2 insertions(+), 12 deletions(-) diff --git a/pandas/_libs/tslibs/period.pyx b/pandas/_libs/tslibs/period.pyx index 9f0e6963d2cc3..1626d1490b440 100644 --- a/pandas/_libs/tslibs/period.pyx +++ b/pandas/_libs/tslibs/period.pyx @@ -1664,18 +1664,8 @@ cdef class PeriodMixin: Examples -------- - >>> period = pd.period_range('2020-1-1 00:00', '2020-3-1 00:00', freq='M') - >>> s = pd.Series(period) - >>> s - 0 2020-01 - 1 2020-02 - 2 2020-03 - dtype: period[M] - >>> s.dt.end_time - 0 2020-01-31 23:59:59.999999999 - 1 2020-02-29 23:59:59.999999999 - 2 2020-03-31 23:59:59.999999999 - dtype: datetime64[ns] + >>> pd.Period('2020-01', 'D').end_time + Timestamp('2020-01-01 23:59:59.999999999') """ return self.to_timestamp(how="end") From 976f77fdaa142a8dd84d7dae97a7ea17ade09149 Mon Sep 17 00:00:00 2001 From: Marco Edward Gorelli Date: Wed, 17 May 2023 12:18:12 +0100 Subject: [PATCH 3/3] Update pandas/core/arrays/datetimes.py --- pandas/core/arrays/datetimes.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pandas/core/arrays/datetimes.py b/pandas/core/arrays/datetimes.py index a8c3580217957..cf99c8ed1a415 100644 --- a/pandas/core/arrays/datetimes.py +++ b/pandas/core/arrays/datetimes.py @@ -565,7 +565,7 @@ def tz(self) -> tzinfo | None: datetime.tzinfo, pytz.tzinfo.BaseTZInfo, dateutil.tz.tz.tzfile, or None Returns None when the array is tz-naive. - Examples + Examples -------- >>> s = pd.Series(["1/1/2020 10:00:00+00:00", "2/1/2020 11:00:00+00:00"]) >>> s = pd.to_datetime(s)