diff --git a/pandas/_libs/tslibs/period.pyx b/pandas/_libs/tslibs/period.pyx index 5895c1242ac71..59db371833957 100644 --- a/pandas/_libs/tslibs/period.pyx +++ b/pandas/_libs/tslibs/period.pyx @@ -54,7 +54,6 @@ from offsets import _Tick cdef bint PY2 = str == bytes - cdef extern from "period_helper.h": int FR_ANN int FR_QTR @@ -1380,34 +1379,49 @@ cdef class _Period(object): @property def dayofweek(self): """ - Return the day of the week. + Day of the week the period lies in, with Monday=0 and Sunday=6. + + If the period frequency is lower than daily (e.g. hourly), and the + period spans over multiple days, the day at the start of the period is + used. - This attribute returns the day of the week on which the particular - date for the given period occurs depending on the frequency with - Monday=0, Sunday=6. + If the frequency is higher than daily (e.g. monthly), the last day + of the period is used. Returns ------- - Int - Range from 0 to 6 (included). + int + Day of the week. - See also + See Also -------- - Period.dayofyear : Return the day of the year. - Period.daysinmonth : Return the number of days in that month. + Period.dayofweek : Day of the week the period lies in. + Period.weekday : Alias of Period.dayofweek. + Period.day : Day of the month. + Period.dayofyear : Day of the year. Examples -------- - >>> period1 = pd.Period('2012-1-1 19:00', freq='H') - >>> period1 - Period('2012-01-01 19:00', 'H') - >>> period1.dayofweek + >>> per = pd.Period('2017-12-31 22:00', 'H') + >>> per.dayofweek + 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 + 6 + >>> per.start_time.dayofweek 6 - >>> period2 = pd.Period('2013-1-9 11:00', freq='H') - >>> period2 - Period('2013-01-09 11:00', 'H') - >>> period2.dayofweek + For periods with a frequency higher than days, the last day of the + period is returned. + + >>> per = pd.Period('2018-01', 'M') + >>> per.dayofweek + 2 + >>> per.end_time.dayofweek 2 """ base, mult = get_freq_code(self.freq) @@ -1415,6 +1429,55 @@ cdef class _Period(object): @property def weekday(self): + """ + Day of the week the period lies in, with Monday=0 and Sunday=6. + + If the period frequency is lower than daily (e.g. hourly), and the + period spans over multiple days, the day at the start of the period is + used. + + If the frequency is higher than daily (e.g. monthly), the last day + of the period is used. + + Returns + ------- + int + Day of the week. + + See Also + -------- + Period.dayofweek : Day of the week the period lies in. + Period.weekday : Alias of Period.dayofweek. + Period.day : Day of the month. + Period.dayofyear : Day of the year. + + Examples + -------- + >>> per = pd.Period('2017-12-31 22:00', 'H') + >>> per.dayofweek + 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 + 6 + >>> per.start_time.dayofweek + 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 + 2 + >>> per.end_time.dayofweek + 2 + """ + # Docstring is a duplicate from dayofweek. Reusing docstrings with + # Appender doesn't work for properties in Cython files, and setting + # the __doc__ attribute is also not possible. return self.dayofweek @property