Add isocalendar property to DatetimeArray

- Add corresponding access properties in accessors
- This calculates the year, week, and day components according to the ISO 8601 calendar and returns them in a data frame.
- It is analogous to Timestamp.isocalendar and datetime.date.isocalendar

Author: mgmarino

pandas/core/arrays/datetimes.py

@@ -182,7 +182,7 @@ class DatetimeArray(dtl.DatetimeLikeArrayMixin, dtl.TimelikeOps, dtl.DatelikeOps
         "microsecond",
         "nanosecond",
     ]
-    _other_ops = ["date", "time", "timetz"]
+    _other_ops = ["date", "time", "timetz", "isocalendar"]
     _datetimelike_ops = _field_ops + _object_ops + _bool_ops + _other_ops
     _datetimelike_methods = [
         "to_period",
@@ -1234,6 +1234,48 @@ def date(self):
 
         return tslib.ints_to_pydatetime(timestamps, box="date")
 
+    @property
+    def isocalendar(self):
+        """
+        Returns a DataFrame with the year, week, and day calculated according to
+        the ISO 8601 standard.
+
+        .. versionadded:: 1.1.0
+
+        Returns
+        -------
+        DataFrame
+            with columns year, week and day
+
+        See Also
+        --------
+        Timestamp.isocalendar
+        datetime.date.isocalendar
+
+        Examples
+        --------
+        >>> idx = pd.date_range(start='2019-12-29', freq='D', periods=4)
+        >>> idx.isocalendar
+           year  week  day
+        0  2019    52    7
+        1  2020     1    1
+        2  2020     1    2
+        3  2020     1    3
+        >>> idx.isocalendar.week
+        0    52
+        1     1
+        2     1
+        3     1
+        Name: week, dtype: int32
+        """
+        from pandas import DataFrame
+
+        sarray = fields.build_isocalendar_sarray(self.asi8)
+        iso_calendar_array = self._maybe_mask_results(
+            sarray, fill_value=np.nan, convert=[(n, "<f8") for n in sarray.dtype.names]
+        )
+        return DataFrame(iso_calendar_array)
+
     year = _field_accessor(
         "year",
         "Y",

pandas/core/indexes/accessors.py

@@ -219,6 +219,40 @@ def to_pydatetime(self) -> np.ndarray:
     def freq(self):
         return self._get_values().inferred_freq
 
+    @property
+    def isocalendar(self):
+        """
+        Returns a DataFrame with the year, week, and day calculated according to
+        the ISO 8601 standard.
+
+        .. versionadded:: 1.1.0
+
+        Returns
+        -------
+        DataFrame
+            with columns year, week and day
+
+        See Also
+        --------
+        Timestamp.isocalendar
+        datetime.date.isocalendar
+
+        Examples
+        --------
+        >>> pd.Series(["2020-01-01"], dtype="datetime64[D]").dt.isocalendar
+           year  week  day
+        0  2020     1    3
+        >>> ser = pd.Series(["2010-01-01", pd.NaT], dtype="datetime64[D]")
+        >>> ser.dt.isocalendar
+             year  week  day
+        0  2009.0  53.0  5.0
+        1     NaN   NaN  NaN
+        >>> pd.Series(["2019-12-31"], dtype="datetime64[D]").dt.isocalendar.week
+        0    1
+        Name: week, dtype: int32
+        """
+        return self._get_values().isocalendar.set_index(self._parent.index)
+
 
 @delegate_names(
     delegate=TimedeltaArray, accessors=TimedeltaArray._datetimelike_ops, typ="property"

pandas/core/indexes/datetimes.py

@@ -89,6 +89,7 @@ def _new_DatetimeIndex(cls, d):
         "date",
         "time",
         "timetz",
+        "isocalendar",
     ]
     + DatetimeArray._bool_ops,
     DatetimeArray,

pandas/tests/series/test_datetime_values.py

@@ -665,3 +665,23 @@ def test_setitem_with_different_tz(self):
             dtype=object,
         )
         tm.assert_series_equal(ser, expected)
+
+    @pytest.mark.parametrize(
+        "input_series, expected_output, expected_type",
+        [
+            [["2020-01-01"], [[2020, 1, 3]], "int32"],
+            [[pd.NaT], [[np.NaN, np.NaN, np.NaN]], "float64"],
+            [["2019-12-31", "2019-12-29"], [[2020, 1, 2], [2019, 52, 7]], "int32"],
+            [
+                ["2010-01-01", pd.NaT],
+                [[2009, 53, 5], [np.NaN, np.NaN, np.NaN]],
+                "float64",
+            ],
+        ],
+    )
+    def test_isocalendar(self, input_series, expected_output, expected_type):
+        ser = pd.Series(input_series, dtype="datetime64[D]")
+        expected_frame = pd.DataFrame(
+            expected_output, columns=["year", "week", "day"]
+        ).astype(expected_type)
+        tm.assert_frame_equal(ser.dt.isocalendar, expected_frame)