From 6232a2ed2590fb8d8b43658adc009688cb30dce2 Mon Sep 17 00:00:00 2001 From: Jordan Murphy <35613487+jordan-d-murphy@users.noreply.github.com> Date: Wed, 21 Feb 2024 23:30:03 -0700 Subject: [PATCH 1/8] fixing PR01 errors for pandas.DatetimeIndex.as_unit and pandas.DatetimeIndex.freq --- ci/code_checks.sh | 2 -- pandas/core/arrays/datetimelike.py | 31 +++++++++++++++++++++++++++++ pandas/core/indexes/datetimelike.py | 3 +++ 3 files changed, 34 insertions(+), 2 deletions(-) diff --git a/ci/code_checks.sh b/ci/code_checks.sh index 04c3ff3a42971..c035b264cefea 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -143,8 +143,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then MSG='Partially validate docstrings (GL08)' ; echo $MSG $BASE_DIR/scripts/validate_docstrings.py --format=actions --errors=GL08 --ignore_functions \ - pandas.DatetimeIndex.as_unit\ - pandas.DatetimeIndex.freq\ pandas.ExcelFile.book\ pandas.ExcelFile.sheet_names\ pandas.Index.empty\ diff --git a/pandas/core/arrays/datetimelike.py b/pandas/core/arrays/datetimelike.py index 38d5205e6b7cb..c151bb9b27d92 100644 --- a/pandas/core/arrays/datetimelike.py +++ b/pandas/core/arrays/datetimelike.py @@ -2151,6 +2151,37 @@ def unit(self) -> str: return dtype_to_unit(self.dtype) # type: ignore[arg-type] def as_unit(self, unit: str, round_ok: bool = True) -> Self: + """ + Convert to a dtype with the given unit resolution. + + Parameters + ---------- + unit : {'s', 'ms', 'us', 'ns'} + + Returns + ------- + same type as self + + Examples + -------- + For :class:`pandas.DatetimeIndex`: + + >>> idx = pd.DatetimeIndex(["2020-01-02 01:02:03.004005006"]) + >>> idx + DatetimeIndex(['2020-01-02 01:02:03.004005006'], + dtype='datetime64[ns]', freq=None) + >>> idx.as_unit("s") + DatetimeIndex(['2020-01-02 01:02:03'], dtype='datetime64[s]', freq=None) + + For :class:`pandas.TimedeltaIndex`: + + >>> tdelta_idx = pd.to_timedelta(["1 day 3 min 2 us 42 ns"]) + >>> tdelta_idx + TimedeltaIndex(['1 days 00:03:00.000002042'], + dtype='timedelta64[ns]', freq=None) + >>> tdelta_idx.as_unit("s") + TimedeltaIndex(['1 days 00:03:00'], dtype='timedelta64[s]', freq=None) + """ if unit not in ["s", "ms", "us", "ns"]: raise ValueError("Supported units are 's', 'ms', 'us', 'ns'") diff --git a/pandas/core/indexes/datetimelike.py b/pandas/core/indexes/datetimelike.py index 8242dc49e6e0d..defc5b0df8716 100644 --- a/pandas/core/indexes/datetimelike.py +++ b/pandas/core/indexes/datetimelike.py @@ -94,6 +94,9 @@ def mean(self, *, skipna: bool = True, axis: int | None = 0): @property def freq(self) -> BaseOffset | None: + """ + Return the frequency object if it is set, otherwise None. + """ return self._data.freq @freq.setter From dfe8cbd3c6ff30bcb2316fe18526e82211180b07 Mon Sep 17 00:00:00 2001 From: Jordan Murphy <35613487+jordan-d-murphy@users.noreply.github.com> Date: Thu, 22 Feb 2024 02:42:20 -0700 Subject: [PATCH 2/8] clean up pandas.DatetimeIndex.freq docstring validation errors --- pandas/core/arrays/datetimelike.py | 26 +++++++++++++++++++++++++- pandas/core/indexes/datetimelike.py | 25 ++++++++++++++++++++++++- 2 files changed, 49 insertions(+), 2 deletions(-) diff --git a/pandas/core/arrays/datetimelike.py b/pandas/core/arrays/datetimelike.py index c151bb9b27d92..e55d8e85ab1af 100644 --- a/pandas/core/arrays/datetimelike.py +++ b/pandas/core/arrays/datetimelike.py @@ -2038,7 +2038,30 @@ def _validate_dtype(cls, values, dtype): def freq(self): """ Return the frequency object if it is set, otherwise None. - """ + + To learn more about the frequency strings, please see `this link + `__. + + See Also + -------- + DatetimeIndex.freq : Return the frequency object if it is set, otherwise None. + PeriodIndex.freq : Return the frequency object if it is set, otherwise None. + + Examples + -------- + >>> datetimeindex = pd.date_range( + ... "2022-02-22 02:22:22", periods=10, tz="America/Chicago", freq="h" + ... ) + >>> datetimeindex + DatetimeIndex(['2022-02-22 02:22:22-06:00', '2022-02-22 03:22:22-06:00', + '2022-02-22 04:22:22-06:00', '2022-02-22 05:22:22-06:00', + '2022-02-22 06:22:22-06:00', '2022-02-22 07:22:22-06:00', + '2022-02-22 08:22:22-06:00', '2022-02-22 09:22:22-06:00', + '2022-02-22 10:22:22-06:00', '2022-02-22 11:22:22-06:00'], + dtype='datetime64[ns, America/Chicago]', freq='h') + >>> datetimeindex.freq + + """ # (http link too long) return self._freq @freq.setter @@ -2157,6 +2180,7 @@ def as_unit(self, unit: str, round_ok: bool = True) -> Self: Parameters ---------- unit : {'s', 'ms', 'us', 'ns'} + round_ok : bool (default True) Returns ------- diff --git a/pandas/core/indexes/datetimelike.py b/pandas/core/indexes/datetimelike.py index defc5b0df8716..77b166676e57b 100644 --- a/pandas/core/indexes/datetimelike.py +++ b/pandas/core/indexes/datetimelike.py @@ -96,7 +96,30 @@ def mean(self, *, skipna: bool = True, axis: int | None = 0): def freq(self) -> BaseOffset | None: """ Return the frequency object if it is set, otherwise None. - """ + + To learn more about the frequency strings, please see `this link + `__. + + See Also + -------- + DatetimeIndex.freq : Return the frequency object if it is set, otherwise None. + PeriodIndex.freq : Return the frequency object if it is set, otherwise None. + + Examples + -------- + >>> datetimeindex = pd.date_range( + ... "2022-02-22 02:22:22", periods=10, tz="America/Chicago", freq="h" + ... ) + >>> datetimeindex + DatetimeIndex(['2022-02-22 02:22:22-06:00', '2022-02-22 03:22:22-06:00', + '2022-02-22 04:22:22-06:00', '2022-02-22 05:22:22-06:00', + '2022-02-22 06:22:22-06:00', '2022-02-22 07:22:22-06:00', + '2022-02-22 08:22:22-06:00', '2022-02-22 09:22:22-06:00', + '2022-02-22 10:22:22-06:00', '2022-02-22 11:22:22-06:00'], + dtype='datetime64[ns, America/Chicago]', freq='h') + >>> datetimeindex.freq + + """ # (http link too long) return self._data.freq @freq.setter From c0dc78b3d9c20c29b74288f7cab074b8013bc33e Mon Sep 17 00:00:00 2001 From: Jordan Murphy <35613487+jordan-d-murphy@users.noreply.github.com> Date: Thu, 22 Feb 2024 23:51:49 -0700 Subject: [PATCH 3/8] update link to use :ref: format --- pandas/core/arrays/datetimelike.py | 6 +++--- pandas/core/indexes/datetimelike.py | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/pandas/core/arrays/datetimelike.py b/pandas/core/arrays/datetimelike.py index e55d8e85ab1af..9a58d95bf8f32 100644 --- a/pandas/core/arrays/datetimelike.py +++ b/pandas/core/arrays/datetimelike.py @@ -2039,8 +2039,8 @@ def freq(self): """ Return the frequency object if it is set, otherwise None. - To learn more about the frequency strings, please see `this link - `__. + To learn more about the frequency strings, please see + :ref:`this link` See Also -------- @@ -2061,7 +2061,7 @@ def freq(self): dtype='datetime64[ns, America/Chicago]', freq='h') >>> datetimeindex.freq - """ # (http link too long) + """ return self._freq @freq.setter diff --git a/pandas/core/indexes/datetimelike.py b/pandas/core/indexes/datetimelike.py index 77b166676e57b..6c9ae5afd8ac1 100644 --- a/pandas/core/indexes/datetimelike.py +++ b/pandas/core/indexes/datetimelike.py @@ -97,8 +97,8 @@ def freq(self) -> BaseOffset | None: """ Return the frequency object if it is set, otherwise None. - To learn more about the frequency strings, please see `this link - `__. + To learn more about the frequency strings, please see + :ref:`this link` See Also -------- @@ -119,7 +119,7 @@ def freq(self) -> BaseOffset | None: dtype='datetime64[ns, America/Chicago]', freq='h') >>> datetimeindex.freq - """ # (http link too long) + """ return self._data.freq @freq.setter From fba7123d0a1a2ac0d5b2f45aeb9baa11335c7cb7 Mon Sep 17 00:00:00 2001 From: Jordan Murphy <35613487+jordan-d-murphy@users.noreply.github.com> Date: Fri, 23 Feb 2024 00:25:12 -0700 Subject: [PATCH 4/8] improving docstring for as_unit --- pandas/core/arrays/datetimelike.py | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/pandas/core/arrays/datetimelike.py b/pandas/core/arrays/datetimelike.py index 9a58d95bf8f32..46aee7ca90c49 100644 --- a/pandas/core/arrays/datetimelike.py +++ b/pandas/core/arrays/datetimelike.py @@ -2180,12 +2180,17 @@ def as_unit(self, unit: str, round_ok: bool = True) -> Self: Parameters ---------- unit : {'s', 'ms', 'us', 'ns'} - round_ok : bool (default True) + round_ok : bool, default True + If False and the conversion requires rounding, raise. Returns ------- same type as self + See Also + -------- + Timestamp.as_unit : Convert to the given unit. + Examples -------- For :class:`pandas.DatetimeIndex`: From b14fbd26836430b402ebfc1f1b50ee73be7ff331 Mon Sep 17 00:00:00 2001 From: Jordan Murphy <35613487+jordan-d-murphy@users.noreply.github.com> Date: Fri, 23 Feb 2024 00:31:54 -0700 Subject: [PATCH 5/8] add missing period --- pandas/core/arrays/datetimelike.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pandas/core/arrays/datetimelike.py b/pandas/core/arrays/datetimelike.py index 46aee7ca90c49..eb6c8b5ca1348 100644 --- a/pandas/core/arrays/datetimelike.py +++ b/pandas/core/arrays/datetimelike.py @@ -2040,7 +2040,7 @@ def freq(self): Return the frequency object if it is set, otherwise None. To learn more about the frequency strings, please see - :ref:`this link` + :ref:`this link`. See Also -------- From e360e337fb31c551db0b0a147526978caeec6fd3 Mon Sep 17 00:00:00 2001 From: Jordan Murphy <35613487+jordan-d-murphy@users.noreply.github.com> Date: Fri, 23 Feb 2024 00:32:26 -0700 Subject: [PATCH 6/8] add missing period --- pandas/core/indexes/datetimelike.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pandas/core/indexes/datetimelike.py b/pandas/core/indexes/datetimelike.py index 6c9ae5afd8ac1..efaf1945c8534 100644 --- a/pandas/core/indexes/datetimelike.py +++ b/pandas/core/indexes/datetimelike.py @@ -98,7 +98,7 @@ def freq(self) -> BaseOffset | None: Return the frequency object if it is set, otherwise None. To learn more about the frequency strings, please see - :ref:`this link` + :ref:`this link`. See Also -------- From c3bee6407d20a8908eab5945c02bb1c5526db186 Mon Sep 17 00:00:00 2001 From: Jordan Murphy <35613487+jordan-d-murphy@users.noreply.github.com> Date: Sat, 24 Feb 2024 20:36:16 -0700 Subject: [PATCH 7/8] Specify ValueError Co-authored-by: Jonas Bergner <44500888+bergnerjonas@users.noreply.github.com> --- pandas/core/arrays/datetimelike.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pandas/core/arrays/datetimelike.py b/pandas/core/arrays/datetimelike.py index eb6c8b5ca1348..a37ad708bdace 100644 --- a/pandas/core/arrays/datetimelike.py +++ b/pandas/core/arrays/datetimelike.py @@ -2181,7 +2181,7 @@ def as_unit(self, unit: str, round_ok: bool = True) -> Self: ---------- unit : {'s', 'ms', 'us', 'ns'} round_ok : bool, default True - If False and the conversion requires rounding, raise. + If False and the conversion requires rounding, raise ValueError. Returns ------- From c71fc2ff7391478014ce0b99c5b1385e11d1dd6e Mon Sep 17 00:00:00 2001 From: Jordan Murphy <35613487+jordan-d-murphy@users.noreply.github.com> Date: Sat, 24 Feb 2024 21:30:51 -0700 Subject: [PATCH 8/8] cleaning up --- ci/code_checks.sh | 2 ++ pandas/core/arrays/datetimelike.py | 4 ++++ 2 files changed, 6 insertions(+) diff --git a/ci/code_checks.sh b/ci/code_checks.sh index 8d1a7d55612a4..d89c64700ffbb 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -71,6 +71,7 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then MSG='Partially validate docstrings (PR02)' ; echo $MSG $BASE_DIR/scripts/validate_docstrings.py --format=actions --errors=PR02 --ignore_functions \ + pandas.Series.dt.as_unit\ pandas.Series.dt.to_period\ pandas.Series.dt.tz_localize\ pandas.Series.dt.tz_convert\ @@ -1494,6 +1495,7 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then pandas.Series.cat.rename_categories\ pandas.Series.cat.reorder_categories\ pandas.Series.cat.set_categories\ + pandas.Series.dt.as_unit\ pandas.Series.dt.ceil\ pandas.Series.dt.day_name\ pandas.Series.dt.floor\ diff --git a/pandas/core/arrays/datetimelike.py b/pandas/core/arrays/datetimelike.py index e57bd3c2872f1..1805a86ee32ce 100644 --- a/pandas/core/arrays/datetimelike.py +++ b/pandas/core/arrays/datetimelike.py @@ -2180,6 +2180,9 @@ def as_unit(self, unit: str, round_ok: bool = True) -> Self: """ Convert to a dtype with the given unit resolution. + The limits of timestamp representation depend on the chosen resolution. + Different resolutions can be converted to each other through as_unit. + Parameters ---------- unit : {'s', 'ms', 'us', 'ns'} @@ -2189,6 +2192,7 @@ def as_unit(self, unit: str, round_ok: bool = True) -> Self: Returns ------- same type as self + Converted to the specified unit. See Also --------