Skip to content

DOC: update the series.dt.weekofyear docstring #20218

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

Closed
wants to merge 10 commits into from
Closed

DOC: update the series.dt.weekofyear docstring #20218

Changes from 8 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
4916ea2
added proper example and edge case in docstring
koaning Mar 10, 2018
d2b5498
Merge remote-tracking branch 'upstream/master' into DOC-series.dt.wee…
koaning Mar 10, 2018
dfd26b3
some pep8 fixes
koaning Mar 10, 2018
f461492
some pep8 fixes
koaning Mar 10, 2018
83e03e2
E128 still failing. requires advice.
koaning Mar 10, 2018
aac1423
wh00ps. wrong return portion
koaning Mar 10, 2018
b5ca86b
made changes based on TomAugspurgers review
koaning Mar 10, 2018
d26938d
spelling
koaning Mar 10, 2018
035f1c5
rewrote return per docs + series to Series
koaning Mar 10, 2018
ec04a59
added comment of multiple occurence
koaning Mar 10, 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
62 changes: 60 additions & 2 deletions pandas/core/indexes/datetimes.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1706,9 +1706,67 @@ def freq(self, value):
"The microseconds of the datetime")
nanosecond = _field_accessor('nanosecond', 'ns',
"The nanoseconds of the datetime")
weekofyear = _field_accessor('weekofyear', 'woy',
"The week ordinal of the year")
_weekofyear_doc = """
Copy link
Contributor

Choose a reason for hiding this comment

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

Ah sorry could you add a trailing backslash to the end of this line? Then we don't have a blank line at the start of the docstring.

Copy link
Author

Choose a reason for hiding this comment

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

When I do that the validation script gives an error.

Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)

Copy link
Contributor

Choose a reason for hiding this comment

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

Ah, nvm you're good then.

The week ordinal of the year.

Return the week ordinal of the year. Note that there can be
counter intuitive edge cases around a year change. For example
the first of january could be in week 52 of the previous year.
Monday indicates the start of a new week.

Returns
-------
ndarray of integers indicating the week number
Copy link
Contributor

Choose a reason for hiding this comment

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

I thikn

days : ndarray
    integers indicating the week number

ndarray is the type, the rest is the ddescription.

Copy link
Author

Choose a reason for hiding this comment

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

Just to confirm, what you're suggesting is different than the docstring guide for the sprint.

Returns
-------
int
    The sum of `num1` and `num2`

example found here: https://python-sprints.github.io/pandas/guide/pandas_docstring.html


See Also
Copy link
Contributor

Choose a reason for hiding this comment

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

I think Returns goes before See Also

Copy link
Author

Choose a reason for hiding this comment

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

well spotted. fixed.

--------
pandas.Series.dt.week : Identical method.
pandas.Series.dt.weekofyear : Identical method.

Examples
--------
>>> dates = pd.date_range("2016-12-31", "2017-01-08", freq="D")
>>> s = pd.Series(dates)
>>> pd.DataFrame({'dt': s, 'week': s.dt.week, 'day': s.dt.strftime("%A")})
Copy link
Contributor

Choose a reason for hiding this comment

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

use s.dt.day_name()

dt week day
0 2016-12-31 52 Saturday
1 2017-01-01 52 Sunday
2 2017-01-02 1 Monday
3 2017-01-03 1 Tuesday
4 2017-01-04 1 Wednesday
5 2017-01-05 1 Thursday
6 2017-01-06 1 Friday
7 2017-01-07 1 Saturday
8 2017-01-08 1 Sunday

Note that `series.dt.week` and `series.dt.weekofyear` are the same.
Copy link
Contributor

Choose a reason for hiding this comment

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

series -> Series

Copy link
Author

Choose a reason for hiding this comment

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

done.


>>> s.dt.week
0 52
1 52
2 1
3 1
4 1
5 1
6 1
7 1
8 1
dtype: int64
>>> s.dt.weekofyear
Copy link
Contributor

Choose a reason for hiding this comment

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

you don't need to repeat them, use weekofyear one

0 52
1 52
2 1
3 1
4 1
5 1
6 1
7 1
8 1
dtype: int64
"""
weekofyear = _field_accessor('weekofyear', 'woy', _weekofyear_doc)
week = weekofyear

dayofweek = _field_accessor('dayofweek', 'dow',
"The day of the week with Monday=0, Sunday=6")
weekday = dayofweek
Expand Down