CLN: Deprecate dayofweek/hello day_of_week (#9606) (#37390)

Author: abhishekmangla

doc/redirects.csv

@@ -542,7 +542,9 @@ generated/pandas.DatetimeIndex.date,../reference/api/pandas.DatetimeIndex.date
 generated/pandas.DatetimeIndex.day,../reference/api/pandas.DatetimeIndex.day
 generated/pandas.DatetimeIndex.day_name,../reference/api/pandas.DatetimeIndex.day_name
 generated/pandas.DatetimeIndex.dayofweek,../reference/api/pandas.DatetimeIndex.dayofweek
+generated/pandas.DatetimeIndex.day_of_week,../reference/api/pandas.DatetimeIndex.day_of_week
 generated/pandas.DatetimeIndex.dayofyear,../reference/api/pandas.DatetimeIndex.dayofyear
+generated/pandas.DatetimeIndex.day_of_year,../reference/api/pandas.DatetimeIndex.day_of_year
 generated/pandas.DatetimeIndex.floor,../reference/api/pandas.DatetimeIndex.floor
 generated/pandas.DatetimeIndex.freq,../reference/api/pandas.DatetimeIndex.freq
 generated/pandas.DatetimeIndex.freqstr,../reference/api/pandas.DatetimeIndex.freqstr
@@ -839,7 +841,9 @@ generated/pandas.option_context,../reference/api/pandas.option_context
 generated/pandas.Period.asfreq,../reference/api/pandas.Period.asfreq
 generated/pandas.Period.day,../reference/api/pandas.Period.day
 generated/pandas.Period.dayofweek,../reference/api/pandas.Period.dayofweek
+generated/pandas.Period.day_of_week,../reference/api/pandas.Period.day_of_week
 generated/pandas.Period.dayofyear,../reference/api/pandas.Period.dayofyear
+generated/pandas.Period.day_of_year,../reference/api/pandas.Period.day_of_year
 generated/pandas.Period.days_in_month,../reference/api/pandas.Period.days_in_month
 generated/pandas.Period.daysinmonth,../reference/api/pandas.Period.daysinmonth
 generated/pandas.Period.end_time,../reference/api/pandas.Period.end_time
@@ -850,7 +854,9 @@ generated/pandas.Period,../reference/api/pandas.Period
 generated/pandas.PeriodIndex.asfreq,../reference/api/pandas.PeriodIndex.asfreq
 generated/pandas.PeriodIndex.day,../reference/api/pandas.PeriodIndex.day
 generated/pandas.PeriodIndex.dayofweek,../reference/api/pandas.PeriodIndex.dayofweek
+generated/pandas.PeriodIndex.day_of_week,../reference/api/pandas.PeriodIndex.day_of_week
 generated/pandas.PeriodIndex.dayofyear,../reference/api/pandas.PeriodIndex.dayofyear
+generated/pandas.PeriodIndex.day_of_year,../reference/api/pandas.PeriodIndex.day_of_year
 generated/pandas.PeriodIndex.days_in_month,../reference/api/pandas.PeriodIndex.days_in_month
 generated/pandas.PeriodIndex.daysinmonth,../reference/api/pandas.PeriodIndex.daysinmonth
 generated/pandas.PeriodIndex.end_time,../reference/api/pandas.PeriodIndex.end_time
@@ -993,7 +999,9 @@ generated/pandas.Series.dt.date,../reference/api/pandas.Series.dt.date
 generated/pandas.Series.dt.day,../reference/api/pandas.Series.dt.day
 generated/pandas.Series.dt.day_name,../reference/api/pandas.Series.dt.day_name
 generated/pandas.Series.dt.dayofweek,../reference/api/pandas.Series.dt.dayofweek
+generated/pandas.Series.dt.day_of_week,../reference/api/pandas.Series.dt.day_of_week
 generated/pandas.Series.dt.dayofyear,../reference/api/pandas.Series.dt.dayofyear
+generated/pandas.Series.dt.day_of_year,../reference/api/pandas.Series.dt.day_of_year
 generated/pandas.Series.dt.days,../reference/api/pandas.Series.dt.days
 generated/pandas.Series.dt.days_in_month,../reference/api/pandas.Series.dt.days_in_month
 generated/pandas.Series.dt.daysinmonth,../reference/api/pandas.Series.dt.daysinmonth
@@ -1326,7 +1334,9 @@ generated/pandas.Timestamp.date,../reference/api/pandas.Timestamp.date
 generated/pandas.Timestamp.day,../reference/api/pandas.Timestamp.day
 generated/pandas.Timestamp.day_name,../reference/api/pandas.Timestamp.day_name
 generated/pandas.Timestamp.dayofweek,../reference/api/pandas.Timestamp.dayofweek
+generated/pandas.Timestamp.day_of_week,../reference/api/pandas.Timestamp.day_of_week
 generated/pandas.Timestamp.dayofyear,../reference/api/pandas.Timestamp.dayofyear
+generated/pandas.Timestamp.day_of_year,../reference/api/pandas.Timestamp.day_of_year
 generated/pandas.Timestamp.days_in_month,../reference/api/pandas.Timestamp.days_in_month
 generated/pandas.Timestamp.daysinmonth,../reference/api/pandas.Timestamp.daysinmonth
 generated/pandas.Timestamp.dst,../reference/api/pandas.Timestamp.dst

doc/source/reference/arrays.rst

@@ -63,7 +63,9 @@ Properties
    Timestamp.asm8
    Timestamp.day
    Timestamp.dayofweek
+   Timestamp.day_of_week
    Timestamp.dayofyear
+   Timestamp.day_of_year
    Timestamp.days_in_month
    Timestamp.daysinmonth
    Timestamp.fold
@@ -233,7 +235,9 @@ Properties
 
    Period.day
    Period.dayofweek
+   Period.day_of_week
    Period.dayofyear
+   Period.day_of_year
    Period.days_in_month
    Period.daysinmonth
    Period.end_time

doc/source/reference/indexing.rst

@@ -345,9 +345,11 @@ Time/date components
    DatetimeIndex.time
    DatetimeIndex.timetz
    DatetimeIndex.dayofyear
+   DatetimeIndex.day_of_year
    DatetimeIndex.weekofyear
    DatetimeIndex.week
    DatetimeIndex.dayofweek
+   DatetimeIndex.day_of_week
    DatetimeIndex.weekday
    DatetimeIndex.quarter
    DatetimeIndex.tz
@@ -461,7 +463,9 @@ Properties
 
     PeriodIndex.day
     PeriodIndex.dayofweek
+    PeriodIndex.day_of_week
     PeriodIndex.dayofyear
+    PeriodIndex.day_of_year
     PeriodIndex.days_in_month
     PeriodIndex.daysinmonth
     PeriodIndex.end_time

doc/source/reference/series.rst

@@ -319,8 +319,10 @@ Datetime properties
    Series.dt.week
    Series.dt.weekofyear
    Series.dt.dayofweek
+   Series.dt.day_of_week
    Series.dt.weekday
    Series.dt.dayofyear
+   Series.dt.day_of_year
    Series.dt.quarter
    Series.dt.is_month_start
    Series.dt.is_month_end

doc/source/user_guide/timeseries.rst

@@ -803,9 +803,11 @@ There are several time/date properties that one can access from ``Timestamp`` or
     time,"Returns datetime.time (does not contain timezone information)"
     timetz,"Returns datetime.time as local time with timezone information"
     dayofyear,"The ordinal day of year"
+    day_of_year,"The ordinal day of year"
     weekofyear,"The week ordinal of the year"
     week,"The week ordinal of the year"
     dayofweek,"The number of the day of the week with Monday=0, Sunday=6"
+    day_of_week,"The number of the day of the week with Monday=0, Sunday=6"
     weekday,"The number of the day of the week with Monday=0, Sunday=6"
     quarter,"Quarter of the date: Jan-Mar = 1, Apr-Jun = 2, etc."
     days_in_month,"The number of days in the month of the datetime"

doc/source/whatsnew/v1.2.0.rst

@@ -207,6 +207,8 @@ level-by-level basis.
 
 Other enhancements
 ^^^^^^^^^^^^^^^^^^
+- Added ``day_of_week``(compatibility alias ``dayofweek``) property to ``Timestamp``, ``DatetimeIndex``, ``Period``, ``PeriodIndex`` (:issue:`9605`)
+- Added ``day_of_year`` (compatibility alias ``dayofyear``) property to ``Timestamp``, ``DatetimeIndex``, ``Period``, ``PeriodIndex`` (:issue:`9605`)
 - Added :meth:`~DataFrame.set_flags` for setting table-wide flags on a ``Series`` or ``DataFrame`` (:issue:`28394`)
 - :meth:`DataFrame.applymap` now supports ``na_action`` (:issue:`23803`)
 - :class:`Index` with object dtype supports division and multiplication (:issue:`34160`)

pandas/_libs/tslibs/nattype.pyx

@@ -357,10 +357,12 @@ class NaTType(_NaT):
 
     week = property(fget=lambda self: np.nan)
     dayofyear = property(fget=lambda self: np.nan)
+    day_of_year = property(fget=lambda self: np.nan)
     weekofyear = property(fget=lambda self: np.nan)
     days_in_month = property(fget=lambda self: np.nan)
     daysinmonth = property(fget=lambda self: np.nan)
     dayofweek = property(fget=lambda self: np.nan)
+    day_of_week = property(fget=lambda self: np.nan)
 
     # inject Timedelta properties
     days = property(fget=lambda self: np.nan)

pandas/_libs/tslibs/period.pyx

@@ -1373,7 +1373,7 @@ cdef accessor _get_accessor_func(str field):
         return <accessor>pweek
     elif field == "day_of_year":
         return <accessor>pday_of_year
-    elif field == "weekday":
+    elif field == "weekday" or field == "day_of_week":
         return <accessor>pweekday
     elif field == "days_in_month":
         return <accessor>pdays_in_month
@@ -1475,6 +1475,9 @@ cdef class _Period(PeriodMixin):
         PeriodDtypeBase _dtype
         BaseOffset freq
 
+    dayofweek = _Period.day_of_week
+    dayofyear = _Period.day_of_year
+
     def __cinit__(self, int64_t ordinal, BaseOffset freq):
         self.ordinal = ordinal
         self.freq = freq
@@ -1882,7 +1885,7 @@ cdef class _Period(PeriodMixin):
         return self.weekofyear
 
     @property
-    def dayofweek(self) -> int:
+    def day_of_week(self) -> int:
         """
         Day of the week the period lies in, with Monday=0 and Sunday=6.
 
@@ -1900,33 +1903,33 @@ cdef class _Period(PeriodMixin):
 
         See Also
         --------
-        Period.dayofweek : Day of the week the period lies in.
-        Period.weekday : Alias of Period.dayofweek.
+        Period.day_of_week : Day of the week the period lies in.
+        Period.weekday : Alias of Period.day_of_week.
         Period.day : Day of the month.
         Period.dayofyear : Day of the year.
 
         Examples
         --------
         >>> per = pd.Period('2017-12-31 22:00', 'H')
-        >>> per.dayofweek
+        >>> per.day_of_week
         6
 
         For periods that span over multiple days, the day at the beginning of
         the period is returned.
 
         >>> per = pd.Period('2017-12-31 22:00', '4H')
-        >>> per.dayofweek
+        >>> per.day_of_week
         6
-        >>> per.start_time.dayofweek
+        >>> per.start_time.day_of_week
         6
 
         For periods with a frequency higher than days, the last day of the
         period is returned.
 
         >>> per = pd.Period('2018-01', 'M')
-        >>> per.dayofweek
+        >>> per.day_of_week
         2
-        >>> per.end_time.dayofweek
+        >>> per.end_time.day_of_week
         2
         """
         base = self._dtype._dtype_code
@@ -1986,7 +1989,7 @@ cdef class _Period(PeriodMixin):
         return self.dayofweek
 
     @property
-    def dayofyear(self) -> int:
+    def day_of_year(self) -> int:
         """
         Return the day of the year.
 
@@ -2002,19 +2005,19 @@ cdef class _Period(PeriodMixin):
         See Also
         --------
         Period.day : Return the day of the month.
-        Period.dayofweek : Return the day of week.
-        PeriodIndex.dayofyear : Return the day of year of all indexes.
+        Period.day_of_week : Return the day of week.
+        PeriodIndex.day_of_year : Return the day of year of all indexes.
 
         Examples
         --------
         >>> period = pd.Period("2015-10-23", freq='H')
-        >>> period.dayofyear
+        >>> period.day_of_year
         296
         >>> period = pd.Period("2012-12-31", freq='D')
-        >>> period.dayofyear
+        >>> period.day_of_year
         366
         >>> period = pd.Period("2013-01-01", freq='D')
-        >>> period.dayofyear
+        >>> period.day_of_year
         1
         """
         base = self._dtype._dtype_code

pandas/_libs/tslibs/timestamps.pyx

@@ -230,6 +230,8 @@ cdef class _Timestamp(ABCTimestamp):
 
     # higher than np.ndarray and np.matrix
     __array_priority__ = 100
+    dayofweek = _Timestamp.day_of_week
+    dayofyear = _Timestamp.day_of_year
 
     def __hash__(_Timestamp self):
         if self.nanosecond:
@@ -538,14 +540,14 @@ cdef class _Timestamp(ABCTimestamp):
         return bool(ccalendar.is_leapyear(self.year))
 
     @property
-    def dayofweek(self) -> int:
+    def day_of_week(self) -> int:
         """
         Return day of the week.
         """
         return self.weekday()
 
     @property
-    def dayofyear(self) -> int:
+    def day_of_year(self) -> int:
         """
         Return the day of the year.
         """

pandas/core/arrays/datetimes.py

@@ -177,7 +177,9 @@ class DatetimeArray(dtl.TimelikeOps, dtl.DatelikeOps):
         "week",
         "weekday",
         "dayofweek",
+        "day_of_week",
         "dayofyear",
+        "day_of_year",
         "quarter",
         "days_in_month",
         "daysinmonth",
@@ -1533,16 +1535,18 @@ def weekofyear(self):
     2017-01-08    6
     Freq: D, dtype: int64
     """
-    dayofweek = _field_accessor("dayofweek", "dow", _dayofweek_doc)
-    weekday = dayofweek
+    day_of_week = _field_accessor("day_of_week", "dow", _dayofweek_doc)
+    dayofweek = day_of_week
+    weekday = day_of_week
 
-    dayofyear = _field_accessor(
+    day_of_year = _field_accessor(
         "dayofyear",
         "doy",
         """
         The ordinal day of the year.
         """,
     )
+    dayofyear = day_of_year
     quarter = _field_accessor(
         "quarter",
         "q",

pandas/core/arrays/period.py

@@ -140,7 +140,9 @@ class PeriodArray(PeriodMixin, dtl.DatelikeOps):
         "weekday",
         "week",
         "dayofweek",
+        "day_of_week",
         "dayofyear",
+        "day_of_year",
         "quarter",
         "qyear",
         "days_in_month",
@@ -381,12 +383,13 @@ def __arrow_array__(self, type=None):
         """,
     )
     week = weekofyear
-    dayofweek = _field_accessor(
-        "weekday",
+    day_of_week = _field_accessor(
+        "day_of_week",
         """
         The day of the week with Monday=0, Sunday=6.
         """,
     )
+    dayofweek = day_of_week
     weekday = dayofweek
     dayofyear = day_of_year = _field_accessor(
         "day_of_year",

pandas/core/indexes/datetimes.py

@@ -164,9 +164,11 @@ class DatetimeIndex(DatetimeTimedeltaMixin):
     time
     timetz
     dayofyear
+    day_of_year
     weekofyear
     week
     dayofweek
+    day_of_week
     weekday
     quarter
     tz

pandas/core/indexes/period.py

@@ -95,7 +95,9 @@ class PeriodIndex(DatetimeIndexOpsMixin, Int64Index):
     ----------
     day
     dayofweek
+    day_of_week
     dayofyear
+    day_of_year
     days_in_month
     daysinmonth
     end_time

pandas/tests/generic/test_finalize.py

@@ -678,7 +678,9 @@ def test_datetime_method(method):
         "microsecond",
         "nanosecond",
         "dayofweek",
+        "day_of_week",
         "dayofyear",
+        "day_of_year",
         "quarter",
         "is_month_start",
         "is_month_end",

pandas/tests/indexes/datetimes/test_scalar_compat.py

@@ -38,7 +38,9 @@ def test_dti_date_out_of_range(self, data):
         "field",
         [
             "dayofweek",
+            "day_of_week",
             "dayofyear",
+            "day_of_year",
             "quarter",
             "days_in_month",
             "is_month_start",

pandas/tests/indexes/period/test_period.py

@@ -249,7 +249,9 @@ def _check_all_fields(self, periodindex):
             "weekofyear",
             "week",
             "dayofweek",
+            "day_of_week",
             "dayofyear",
+            "day_of_year",
             "quarter",
             "qyear",
             "days_in_month",