Deprecate week and weekofyear in Series.dt/DatetimeIndex

Author: mgmarino

pandas/core/arrays/datetimes.py

@@ -1298,6 +1298,32 @@ def isocalendar(self):
             iso_calendar_df.iloc[self._isnan] = None
         return iso_calendar_df
 
+    @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=3,
+        )
+        return pd.Int64Index(self.isocalendar().week)
+
+    week = weekofyear
+
     year = _field_accessor(
         "year",
         "Y",
@@ -1482,14 +1508,6 @@ def isocalendar(self):
         dtype: int64
         """,
     )
-    weekofyear = _field_accessor(
-        "weekofyear",
-        "woy",
-        """
-        The week ordinal of the year.
-        """,
-    )
-    week = weekofyear
     _dayofweek_doc = """
     The day of the week with Monday=0, Sunday=6.
 

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/tests/indexes/datetimes/test_misc.py

@@ -383,6 +383,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

@@ -684,3 +684,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