Fix pandas deprecation warnings

Author: spencerkclark

_stubtest/allowlist.txt

@@ -107,7 +107,9 @@ xarray\.core\.dataset\.DatasetResample$
 
 xarray\.core\.(dataarray|dataset)\.CFTimeIndex\.date_type$
 xarray\.core\.(dataarray|dataset)\.CFTimeIndex\.day$
+xarray\.core\.(dataarray|dataset)\.CFTimeIndex\.day_of_week$
 xarray\.core\.(dataarray|dataset)\.CFTimeIndex\.dayofweek$
+xarray\.core\.(dataarray|dataset)\.CFTimeIndex\.day_of_year$
 xarray\.core\.(dataarray|dataset)\.CFTimeIndex\.dayofyear$
 xarray\.core\.(dataarray|dataset)\.CFTimeIndex\.days_in_month$
 xarray\.core\.(dataarray|dataset)\.CFTimeIndex\.hour$

doc/api-hidden.rst

@@ -114,7 +114,9 @@
    core.accessor_dt.DatetimeAccessor.date
    core.accessor_dt.DatetimeAccessor.day
    core.accessor_dt.DatetimeAccessor.dayofweek
+   core.accessor_dt.DatetimeAccessor.day_of_week
    core.accessor_dt.DatetimeAccessor.dayofyear
+   core.accessor_dt.DatetimeAccessor.day_of_year
    core.accessor_dt.DatetimeAccessor.days_in_month
    core.accessor_dt.DatetimeAccessor.daysinmonth
    core.accessor_dt.DatetimeAccessor.hour
@@ -409,6 +411,8 @@
    CFTimeIndex.ceil
    CFTimeIndex.contains
    CFTimeIndex.copy
+   CFTimeIndex.day_of_week
+   CFTimeIndex.day_of_year
    CFTimeIndex.days_in_month
    CFTimeIndex.delete
    CFTimeIndex.difference

doc/api/dataarray.rst

@@ -272,8 +272,10 @@ Datetimelike properties
    DataArray.dt.second
    DataArray.dt.microsecond
    DataArray.dt.nanosecond
+   DataArray.dt.day_of_week
    DataArray.dt.dayofweek
    DataArray.dt.weekday
+   DataArray.dt.day_of_year
    DataArray.dt.dayofyear
    DataArray.dt.quarter
    DataArray.dt.days_in_month

doc/getting-started-guide/why-xarray.rst

@@ -28,7 +28,7 @@ powerful and concise interface. For example:
    dimensions (array broadcasting) based on dimension names, not shape.
 -  Easily use the `split-apply-combine <https://vita.had.co.nz/papers/plyr.pdf>`_
    paradigm with ``groupby``:
-   ``x.groupby('time.dayofyear').mean()``.
+   ``x.groupby('time.day_of_year').mean()``.
 -  Database-like alignment based on coordinate labels that smoothly
    handles missing values: ``x, y = xr.align(x, y, join='outer')``.
 -  Keep track of arbitrary metadata in the form of a Python dictionary:

doc/user-guide/time-series.rst

@@ -150,15 +150,15 @@ given ``DataArray`` can be quickly computed using a special ``.dt`` accessor.
 
 .. jupyter-execute::
 
-    ds.time.dt.dayofweek
+    ds.time.dt.day_of_week
 
 The ``.dt`` accessor works on both coordinate dimensions as well as
 multi-dimensional data.
 
 Xarray also supports a notion of "virtual" or "derived" coordinates for
 `datetime components`__ implemented by pandas, including "year", "month",
-"day", "hour", "minute", "second", "dayofyear", "week", "dayofweek", "weekday"
-and "quarter":
+"day", "hour", "minute", "second", "day_of_year", "week", "day_of_week", and
+"quarter":
 
 __ https://pandas.pydata.org/pandas-docs/stable/api.html#time-date-components
 
@@ -168,7 +168,7 @@ __ https://pandas.pydata.org/pandas-docs/stable/api.html#time-date-components
 
 .. jupyter-execute::
 
-    ds["time.dayofyear"]
+    ds["time.day_of_year"]
 
 For use as a derived coordinate, xarray adds ``'season'`` to the list of
 datetime components supported by pandas:

doc/user-guide/weather-climate.rst

@@ -184,8 +184,8 @@ For data indexed by a :py:class:`~xarray.CFTimeIndex` xarray currently supports:
 
 - Access of basic datetime components via the ``dt`` accessor (in this case
   just "year", "month", "day", "hour", "minute", "second", "microsecond",
-  "season", "dayofyear", "dayofweek", and "days_in_month") with the addition
-  of "calendar", absent from pandas:
+  "season", "day_of_year", "day_of_week", and "days_in_month") with the
+  addition of "calendar", absent from pandas:
 
 .. jupyter-execute::
 
@@ -201,11 +201,11 @@ For data indexed by a :py:class:`~xarray.CFTimeIndex` xarray currently supports:
 
 .. jupyter-execute::
 
-    da.time.dt.dayofyear
+    da.time.dt.day_of_year
 
 .. jupyter-execute::
 
-    da.time.dt.dayofweek
+    da.time.dt.day_of_week
 
 .. jupyter-execute::
 

doc/whats-new.rst

@@ -104,7 +104,25 @@ Breaking Changes
 
 Deprecations
 ~~~~~~~~~~~~
-
+- Following pandas, on xarray's
+  :py:class:`~xarray.core.accessor_dt.DatetimeAccessor`,
+  :py:attr:`~xarray.core.accessor_dt.DatetimeAccessor.daysinmonth`
+  is deprecated in favor of
+  :py:attr:`~xarray.core.accessor_dt.DatetimeAccessor.days_in_month`;
+  :py:attr:`~xarray.core.accessor_dt.DatetimeAccessor.dayofweek` and
+  :py:attr:`~xarray.core.accessor_dt.DatetimeAccessor.weekday` are deprecated
+  in favor of :py:attr:`~xarray.core.accessor_dt.DatetimeAccessor.day_of_week`;
+  and :py:attr:`~xarray.core.accessor_dt.DatetimeAccessor.dayofyear` is
+  deprecated in favor of
+  :py:attr:`~xarray.core.accessor_dt.DatetimeAccessor.day_of_year`
+  (:issue:`11268`, :pull:`11270`). By `Spencer Clark
+  <https://github.com/spencerkclark>`_.
+- Following pandas, on xarray's :py:class:`~xarray.CFTimeIndex`,
+  :py:attr:`~xarray.CFTimeIndex.dayofweek` and
+  :py:attr:`~xarray.CFTimeIndex.dayofyear` are deprecated in favor of
+  :py:attr:`~xarray.CFTimeIndex.day_of_week` and
+  :py:attr:`~xarray.CFTimeIndex.day_of_year`, respectively (:pull:`11270`).
+  By `Spencer Clark <https://github.com/spencerkclark>`_.
 
 Bug Fixes
 ~~~~~~~~~

xarray/coding/calendar_ops.py

@@ -249,7 +249,7 @@ def _interpolate_day_of_year(times, target_calendar):
     source_calendar = times.dt.calendar
     return np.round(
         _days_in_year(times.dt.year, target_calendar)
-        * times.dt.dayofyear
+        * times.dt.day_of_year
         / _days_in_year(times.dt.year, source_calendar)
     ).astype(int)
 
@@ -272,7 +272,7 @@ def _random_day_of_year(time, target_calendar, use_cftime):
         new_doy = np.insert(new_doy, rm_idx - np.arange(5), -1)
         if _days_in_year(year, source_calendar) == 366:
             new_doy = np.insert(new_doy, 60, -1)
-    return new_doy[time.dt.dayofyear - 1]
+    return new_doy[time.dt.day_of_year - 1]
 
 
 def _convert_to_new_calendar_with_new_day_of_year(

xarray/coding/cftime_offsets.py

@@ -1623,10 +1623,18 @@ def date_range_like(source, calendar, use_cftime=None):
     end = convert_time_or_go_back(source_end, date_type)
 
     # For the cases where the source ends on the end of the month, we expect the same in the new calendar.
-    if source_end.day == source_end.daysinmonth and isinstance(
+    if isinstance(source_end, pd.Timestamp):
+        source_end_days_in_month = source_end.days_in_month
+    else:
+        source_end_days_in_month = source_end.daysinmonth
+    if isinstance(end, pd.Timestamp):
+        end_days_in_month = end.days_in_month
+    else:
+        end_days_in_month = end.daysinmonth
+    if source_end.day == source_end_days_in_month and isinstance(
         freq_as_offset, YearEnd | QuarterEnd | MonthEnd | Day
     ):
-        end = end.replace(day=end.daysinmonth)
+        end = end.replace(day=end_days_in_month)
 
     return date_range(
         start=start.isoformat(),

xarray/coding/cftimeindex.py

@@ -127,7 +127,12 @@ def get_date_field(datetimes, field):
     return np.array([getattr(date, field) for date in datetimes], dtype=np.int64)
 
 
-def _field_accessor(name, docstring=None, min_cftime_version="0.0"):
+def _field_accessor(
+    name: str,
+    docstring: str | None = None,
+    min_cftime_version: str = "0.0",
+    deprecation_pair: tuple[str, str] | None = None,
+):
     """Adapted from pandas.tseries.index._field_accessor"""
 
     def f(self, min_cftime_version=min_cftime_version):
@@ -136,6 +141,14 @@ def f(self, min_cftime_version=min_cftime_version):
         else:
             cftime = attempt_import("cftime")
 
+        if deprecation_pair is not None:
+            original, replacement = deprecation_pair
+            emit_user_level_warning(
+                f"CFTimeIndex.{original} is deprecated and will be removed in "
+                f"a future version. Use CFTimeIndex.{replacement} instead",
+                FutureWarning,
+            )
+
         if Version(cftime.__version__) >= Version(min_cftime_version):
             return get_date_field(self._data, name)
         else:
@@ -249,9 +262,23 @@ class CFTimeIndex(pd.Index):
     second = _field_accessor("second", "The seconds of the datetime")
     microsecond = _field_accessor("microsecond", "The microseconds of the datetime")
     dayofyear = _field_accessor(
+        "dayofyr",
+        "The ordinal day of year of the datetime",
+        "1.0.2.1",
+        ("dayofyear", "day_of_year"),
+    )
+    dayofweek = _field_accessor(
+        "dayofwk",
+        "The day of week of the datetime",
+        "1.0.2.1",
+        ("dayofweek", "day_of_week"),
+    )
+    day_of_year = _field_accessor(
         "dayofyr", "The ordinal day of year of the datetime", "1.0.2.1"
     )
-    dayofweek = _field_accessor("dayofwk", "The day of week of the datetime", "1.0.2.1")
+    day_of_week = _field_accessor(
+        "dayofwk", "The day of week of the datetime", "1.0.2.1"
+    )
     days_in_month = _field_accessor(
         "daysinmonth", "The number of days in the month of the datetime", "1.1.0.0"
     )