Skip to content

DOC: fixing GL08 errors for pandas.DatetimeIndex.as_unit and pandas.DatetimeIndex.freq #57562

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 10 commits into from
Feb 26, 2024
4 changes: 2 additions & 2 deletions ci/code_checks.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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\
Expand Down Expand Up @@ -143,8 +144,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\
Expand Down Expand Up @@ -1496,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\
Expand Down
64 changes: 64 additions & 0 deletions pandas/core/arrays/datetimelike.py
Original file line number Diff line number Diff line change
Expand Up @@ -2041,6 +2041,29 @@ 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
:ref:`this link<timeseries.offset_aliases>`.

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
<Hour>
"""
return self._freq

Expand Down Expand Up @@ -2154,6 +2177,47 @@ 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.

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'}
round_ok : bool, default True
If False and the conversion requires rounding, raise ValueError.

Returns
-------
same type as self
Converted to the specified unit.

See Also
--------
Timestamp.as_unit : Convert to the given unit.

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'")

Expand Down
26 changes: 26 additions & 0 deletions pandas/core/indexes/datetimelike.py
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,32 @@ 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.

To learn more about the frequency strings, please see
:ref:`this link<timeseries.offset_aliases>`.

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
<Hour>
"""
return self._data.freq

@freq.setter
Expand Down