Skip to content

DOC : update the pandas.Period.weekday docstring #20413

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jul 18, 2018
Merged

DOC : update the pandas.Period.weekday docstring #20413

Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
c9282d7
DOC : update docstring
IHackPy Mar 19, 2018
45a7754
Merge remote-tracking branch 'upstream/master' into docstring_head.pe…
datapythonista Jul 9, 2018
82084bf
Being more specific on what dayofweek returns for periods
datapythonista Jul 9, 2018
eaf6c77
Merge remote-tracking branch 'upstream/master' into docstring_head.pe…
datapythonista Jul 17, 2018
fcaaf4b
Fixed typo in docstring
datapythonista Jul 17, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
99 changes: 81 additions & 18 deletions pandas/_libs/tslibs/period.pyx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,6 @@ from offsets import _Tick

cdef bint PY2 = str == bytes


cdef extern from "period_helper.h":
int FR_ANN
int FR_QTR
Expand Down Expand Up @@ -1384,41 +1383,105 @@ 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 frequancy higher than days, the last day of the
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

typo frequency

period is returned.

>>> per = pd.Period('2018-01', 'M')
>>> per.dayofweek
2
>>> per.end_time.dayofweek
2
"""
base, mult = get_freq_code(self.freq)
return pweekday(self.ordinal, base)

@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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the examples give the idea that a Period is a single day. I'd use a Period for a quarter that should make it clearer that this is not a single day.

And also, or here or in the summary, give more details on which day of the week of the 3 months period is being returned.


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 frequancy higher than days, the last day of the
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

typo frequency

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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would it work using syntax to the effect of weekday = property(dayofweek.fget, doc=dayofweek.__doc__)?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the feedback. That's actually a great idea, didn't know property had an argument for the doc. Unfortunately this doesn't seem to be supported in cython:

    weekday = property(dayofweek.fget, doc=dayofweek.__doc__)
                      ^
------------------------------------------------------------

pandas/_libs/tslibs/period.pyx:1430:23: 'dayofweek' is not a constant, variable or function identifier

return self.dayofweek

@property
Expand Down