Silence datetime accessor deprecation warnings

_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

@@ -62,6 +62,16 @@ New Features
   By `Michael Niklas <https://github.com/headtr1ck>`_.
 - Added complex dtype support to FillValueCoder for the Zarr backend. (:pull:`11151`)
   By `Max Jones <https://github.com/maxrjones>`_.
+- Following pandas, xarray's
+  :py:class:`~xarray.core.accessor_dt.DatetimeAccessor` now supports
+  :py:attr:`~xarray.core.accessor_dt.DatetimeAccessor.day_of_week` and
+  :py:attr:`~xarray.core.accessor_dt.DatetimeAccessor.day_of_year` attributes,
+  which are alternative names for the existing
+  :py:attr:`~xarray.core.accessor_dt.DatetimeAccessor.dayofweek` and
+  :py:attr:`~xarray.core.accessor_dt.DatetimeAccessor.dayofyear` attributes.
+  These alternative attributes have similarly been added to
+  :py:class:`~xarray.CFTimeIndex` (:pull:`11270`). By `Spencer Clark
+  <https://github.com/spencerkclark>`_.
 - Added ``facetgrid_figsize`` option to :py:func:`~xarray.set_options` allowing
   :py:class:`~xarray.plot.FacetGrid` to use ``matplotlib.rcParams['figure.figsize']``
   or a fixed ``(width, height)`` tuple instead of computing figure size from
@@ -183,6 +193,16 @@ Bug Fixes
   By `Amartya Anand <https://github.com/SurfyPenguin>`_.
 - Fix h5netcdf backend module detection and ros3 tests (:issue:`11243`, :pull:`11274`).
   By `Kai Mühlbauer <https://github.com/kmuehlbauer>`_.
+- The names of :py:class:`~xarray.DataArray` objects returned by properties of
+  the :py:class:`~xarray.core.accessor_dt.DatetimeAccessor` now always match
+  the property names. Previously properties like
+  :py:attr:`~xarray.core.accessor_dt.DatetimeAccessor.days_in_month`,
+  :py:attr:`~xarray.core.accessor_dt.DatetimeAccessor.weekday`, and
+  :py:attr:`~xarray.core.accessor_dt.DatetimeAccessor.weekofyear` would return
+  :py:class:`~xarray.DataArray` objects named ``"daysinmonth"``,
+  ``"dayofweek"``, and ``"week"``, respectively; now they return objects named
+  ``"days_in_month"``, ``"weekday"``, and ``"weekofyear"`` (:pull:`11270`). By
+  `Spencer Clark <https://github.com/spencerkclark>`_.
 
 Documentation
 ~~~~~~~~~~~~~

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,11 @@ 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",
+):
     """Adapted from pandas.tseries.index._field_accessor"""
 
     def f(self, min_cftime_version=min_cftime_version):
@@ -249,9 +253,21 @@ 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",
+    )
+    dayofweek = _field_accessor(
+        "dayofwk",
+        "The day of week of the datetime",
+        "1.0.2.1",
+    )
+    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"
     )

xarray/core/accessor_dt.py

@@ -338,8 +338,8 @@ class DatetimeAccessor(TimeAccessor[T_DataArray]):
       * time     (time) datetime64[us] 80B 2000-01-01 2000-01-02 ... 2000-01-10
     >>> ts.dt  # doctest: +ELLIPSIS
     <xarray.core.accessor_dt.DatetimeAccessor object at 0x...>
-    >>> ts.dt.dayofyear
-    <xarray.DataArray 'dayofyear' (time: 10)> Size: 80B
+    >>> ts.dt.day_of_year
+    <xarray.DataArray 'day_of_year' (time: 10)> Size: 80B
     array([ 1,  2,  3,  4,  5,  6,  7,  8,  9, 10])
     Coordinates:
       * time     (time) datetime64[us] 80B 2000-01-01 2000-01-02 ... 2000-01-10
@@ -459,23 +459,45 @@ def weekofyear(self) -> DataArray:
             stacklevel=2,
         )
 
-        weekofyear = self.isocalendar().week
+        return self.isocalendar().week.rename("weekofyear")
 
-        return weekofyear
+    @property
+    def week(self) -> DataArray:
+        "The week ordinal of the year"
+
+        warnings.warn(
+            "dt.weekofyear and dt.week have been deprecated. Please use "
+            "dt.isocalendar().week instead.",
+            FutureWarning,
+            stacklevel=2,
+        )
 
-    week = weekofyear
+        return self.isocalendar().week
+
+    @property
+    def day_of_week(self) -> T_DataArray:
+        """The day of the week with Monday=0, Sunday=6"""
+        return self._date_field("day_of_week", np.int64)
 
     @property
     def dayofweek(self) -> T_DataArray:
         """The day of the week with Monday=0, Sunday=6"""
-        return self._date_field("dayofweek", np.int64)
+        return self._date_field("day_of_week", np.int64).rename("dayofweek")
 
-    weekday = dayofweek
+    @property
+    def weekday(self) -> T_DataArray:
+        """The day of the week with Monday=0, Sunday=6"""
+        return self._date_field("day_of_week", np.int64).rename("weekday")
+
+    @property
+    def day_of_year(self) -> T_DataArray:
+        """The ordinal day of the year"""
+        return self._date_field("day_of_year", np.int64)
 
     @property
     def dayofyear(self) -> T_DataArray:
         """The ordinal day of the year"""
-        return self._date_field("dayofyear", np.int64)
+        return self._date_field("day_of_year", np.int64).rename("dayofyear")
 
     @property
     def quarter(self) -> T_DataArray:
@@ -487,7 +509,10 @@ def days_in_month(self) -> T_DataArray:
         """The number of days in the month"""
         return self._date_field("days_in_month", np.int64)
 
-    daysinmonth = days_in_month
+    @property
+    def daysinmonth(self) -> T_DataArray:
+        """The number of days in the month"""
+        return self._date_field("days_in_month", np.int64).rename("daysinmonth")
 
     @property
     def season(self) -> T_DataArray:

xarray/core/dataarray.py

@@ -6978,21 +6978,21 @@ def groupby(
                1.826e+03], shape=(1827,))
         Coordinates:
           * time     (time) datetime64[us] 15kB 2000-01-01 2000-01-02 ... 2004-12-31
-        >>> da.groupby("time.dayofyear") - da.groupby("time.dayofyear").mean("time")
+        >>> da.groupby("time.day_of_year") - da.groupby("time.day_of_year").mean("time")
         <xarray.DataArray (time: 1827)> Size: 15kB
         array([-730.8, -730.8, -730.8, ...,  730.2,  730.2,  730.5], shape=(1827,))
         Coordinates:
-          * time       (time) datetime64[us] 15kB 2000-01-01 2000-01-02 ... 2004-12-31
-            dayofyear  (time) int64 15kB 1 2 3 4 5 6 7 8 ... 360 361 362 363 364 365 366
+          * time         (time) datetime64[us] 15kB 2000-01-01 2000-01-02 ... 2004-12-31
+            day_of_year  (time) int64 15kB 1 2 3 4 5 6 7 ... 360 361 362 363 364 365 366
 
         Use a ``Grouper`` object to be more explicit
 
-        >>> da.coords["dayofyear"] = da.time.dt.dayofyear
-        >>> da.groupby(dayofyear=xr.groupers.UniqueGrouper()).mean()
-        <xarray.DataArray (dayofyear: 366)> Size: 3kB
+        >>> da.coords["day_of_year"] = da.time.dt.day_of_year
+        >>> da.groupby(day_of_year=xr.groupers.UniqueGrouper()).mean()
+        <xarray.DataArray (day_of_year: 366)> Size: 3kB
         array([ 730.8,  731.8,  732.8, ..., 1093.8, 1094.8, 1095.5])
         Coordinates:
-          * dayofyear  (dayofyear) int64 3kB 1 2 3 4 5 6 7 ... 361 362 363 364 365 366
+          * day_of_year  (day_of_year) int64 3kB 1 2 3 4 5 6 ... 361 362 363 364 365 366
 
         >>> da = xr.DataArray(
         ...     data=np.arange(12).reshape((4, 3)),

xarray/tests/test_accessor_dt.py

@@ -58,7 +58,9 @@ def setup(self):
             "weekofyear",
             "dayofweek",
             "weekday",
+            "day_of_week",
             "dayofyear",
+            "day_of_year",
             "quarter",
             "date",
             "time",
@@ -77,20 +79,20 @@ def test_field_access(self, field) -> None:
         if field in ["week", "weekofyear"]:
             data = self.times.isocalendar()["week"]
         else:
-            data = getattr(self.times, field)
+            pandas_translations = {
+                "weekday": "day_of_week",
+                "dayofweek": "day_of_week",
+                "daysinmonth": "days_in_month",
+                "dayofyear": "day_of_year",
+            }
+            pandas_name = pandas_translations.get(field, field)
+            data = getattr(self.times, pandas_name)
 
         if data.dtype.kind != "b" and field not in ("date", "time"):
             # pandas 2.0 returns int32 for integer fields now
             data = data.astype("int64")
 
-        translations = {
-            "weekday": "dayofweek",
-            "daysinmonth": "days_in_month",
-            "weekofyear": "week",
-        }
-        name = translations.get(field, field)
-
-        expected = xr.DataArray(data, name=name, coords=[self.times], dims=["time"])
+        expected = xr.DataArray(data, name=field, coords=[self.times], dims=["time"])
 
         if field in ["week", "weekofyear"]:
             with pytest.warns(
@@ -179,7 +181,9 @@ def test_not_datetime_type(self) -> None:
             "weekofyear",
             "dayofweek",
             "weekday",
+            "day_of_week",
             "dayofyear",
+            "day_of_year",
             "quarter",
             "date",
             "time",
@@ -441,7 +445,7 @@ def times_3d(times):
 
 @requires_cftime
 @pytest.mark.parametrize(
-    "field", ["year", "month", "day", "hour", "dayofyear", "dayofweek"]
+    "field", ["year", "month", "day", "hour", "day_of_year", "day_of_week"]
 )
 def test_field_access(data, field) -> None:
     result = getattr(data.time.dt, field)
@@ -533,7 +537,7 @@ def test_cftime_strftime_access(data) -> None:
 @requires_cftime
 @requires_dask
 @pytest.mark.parametrize(
-    "field", ["year", "month", "day", "hour", "dayofyear", "dayofweek"]
+    "field", ["year", "month", "day", "hour", "day_of_year", "day_of_week"]
 )
 def test_dask_field_access_1d(data, field) -> None:
     import dask.array as da
@@ -553,7 +557,7 @@ def test_dask_field_access_1d(data, field) -> None:
 @requires_cftime
 @requires_dask
 @pytest.mark.parametrize(
-    "field", ["year", "month", "day", "hour", "dayofyear", "dayofweek"]
+    "field", ["year", "month", "day", "hour", "day_of_year", "day_of_week"]
 )
 def test_dask_field_access(times_3d, data, field) -> None:
     import dask.array as da