Deprecate week and weekofyear in Series.dt/DatetimeIndex

Author: mgmarino

pandas/core/indexes/accessors.py

@@ -250,6 +250,32 @@ def isocalendar(self):
         """
         return self._get_values().isocalendar().set_index(self._parent.index)
 
+    @property
+    def weekofyear(self):
+        """
+        The week ordinal of the year.
+
+        .. deprecated:: 1.1.0
+
+        Series.dt.weekofyear and Series.dt.week have been deprecated.
+        Please use Series.dt.isocalendar().week instead.
+        """
+        import warnings
+
+        warnings.warn(
+            "Series.dt.weekofyear and Series.dt.week have been deprecated.  "
+            "Please use Series.dt.isocalendar().week instead.",
+            FutureWarning,
+            stacklevel=2,
+        )
+        week_series = self.isocalendar().week
+        week_series.name = self.name
+        if week_series.hasnans:
+            return week_series.astype("float64")
+        return week_series.astype("int64")
+
+    week = weekofyear
+
 
 @delegate_names(
     delegate=TimedeltaArray, accessors=TimedeltaArray._datetimelike_ops, typ="property"

pandas/core/indexes/datetimes.py

@@ -809,6 +809,32 @@ def indexer_between_time(
 
         return mask.nonzero()[0]
 
+    @property
+    def weekofyear(self):
+        """
+        The week ordinal of the year.
+
+        .. deprecated:: 1.1.0
+
+        weekofyear and week have been deprecated.
+        Please use DatetimeIndex.isocalendar().week instead.
+        """
+        import pandas as pd
+        import warnings
+
+        warnings.warn(
+            "weekofyear and week have been deprecated, please use "
+            "DatetimeIndex.isocalendar().week instead, which returns "
+            "a Series.  To exactly reproduce the behavior of week and "
+            "weekofyear and return an Index, you may call "
+            "pd.Int64Index(idx.isocalendar().week)",
+            FutureWarning,
+            stacklevel=2,
+        )
+        return pd.Int64Index(self.isocalendar().week)
+
+    week = weekofyear
+
 
 DatetimeIndex._add_numeric_methods_disabled()
 DatetimeIndex._add_logical_methods_disabled()

pandas/tests/indexes/datetimes/test_misc.py

@@ -375,6 +375,14 @@ def test_iter_readonly():
     list(dti)
 
 
+def test_week_and_weekofyear_are_deprecated():
+    idx = pd.date_range(start="2019-12-29", freq="D", periods=4)
+    with tm.assert_produces_warning(FutureWarning):
+        idx.week
+    with tm.assert_produces_warning(FutureWarning):
+        idx.weekofyear
+
+
 def test_isocalendar_returns_correct_values_close_to_new_year_with_tz():
     # GH 6538: Check that DatetimeIndex and its TimeStamp elements
     # return the same weekofyear accessor close to new year w/ tz

pandas/tests/series/test_datetime_values.py

@@ -50,6 +50,8 @@ def test_dt_namespace_accessor(self):
             "day_name",
             "month_name",
             "isocalendar",
+            "week",
+            "weekofyear",
         ]
         ok_for_td = TimedeltaIndex._datetimelike_ops
         ok_for_td_methods = [
@@ -684,3 +686,11 @@ def test_isocalendar(self, input_series, expected_output):
             expected_output, columns=["year", "week", "day"], dtype="UInt32"
         )
         tm.assert_frame_equal(result, expected_frame)
+
+
+def test_week_and_weekofyear_are_deprecated():
+    series = pd.to_datetime(pd.Series(["2020-01-01"]))
+    with tm.assert_produces_warning(FutureWarning):
+        series.dt.week
+    with tm.assert_produces_warning(FutureWarning):
+        series.dt.weekofyear