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

koaning · 2018-03-10T19:04:44Z

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

PR title is "DOC: update the docstring"
The validation script passes: scripts/validate_docstrings.py <your-function-or-method>
The PEP8 style check passes: git diff upstream/master -u -- "*.py" | flake8 --diff
The html version looks good: python doc/make.py --single <your-function-or-method>
It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

################################################################################
###################### Docstring (pandas.Series.dt.week)  ######################
################################################################################

The week ordinal of the year.

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

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

Returns
-------
ndarray of integers indicating week

Examples
--------
>>> dates = pd.date_range("2016-12-31", "2017-01-08", freq="D")
>>> s = pd.Series(dates)
>>> pd.DataFrame({'date':s, 'week':s.dt.week, 'day':s.dt.strftime("%A")})
        date  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 what `series.dt.week` and `series.dt.weekofyear` are the same.

>>> 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
0    52
1    52
2     1
3     1
4     1
5     1
6     1
7     1
8     1
dtype: int64

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.Series.dt.week" correct. :)

If the validation script still gives errors, but you think there is a good reason
to deviate in this case (and there are certainly such cases), please state this
explicitly.

…kofyear

pep8speaks · 2018-03-10T19:04:46Z

Hello @koaning! Thanks for updating the PR.

Cheers ! There are no PEP8 issues in this Pull Request. 🍻

Comment last updated on March 10, 2018 at 21:39 Hours UTC

koaning · 2018-03-10T19:12:39Z

Mhm. Strange, locally I didn't seem to have PEP8 issues. Will check!

koaning · 2018-03-10T19:23:05Z

pandas/core/indexes/datetimes.py

@@ -1707,7 +1707,64 @@ def freq(self, value):
    nanosecond = _field_accessor('nanosecond', 'ns',
                                 "The nanoseconds of the datetime")
    weekofyear = _field_accessor('weekofyear', 'woy',
-                                 "The week ordinal of the year")
+    """


This is where E128 is still complaining a bit. I don't know what the nicest way is to resolve this since we're a bit unconventional with the _field_accessor accepting a docstring here. I could add tabs to the docstring, but it would make the code much less readable (as well cause ugly things to the docstring).

@TomAugspurger would love advice.

@koaning maybe just make a new variable called _weekofyear_doc and assign it to like

weekofyear = _field_accessor('weekofyear', 'woy', _weekofyear_doc)

you'll get a lot of variables in that file, but that works for me. will make the change. thanks!

TomAugspurger · 2018-03-10T19:29:41Z

pandas/core/indexes/datetimes.py

+    the first of january could be in week 52 of the previous year.
+    Monday indicates the start of a new week.
+
+    See Also


I think Returns goes before See Also

well spotted. fixed.

TomAugspurger · 2018-03-10T19:30:03Z

pandas/core/indexes/datetimes.py

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


pep8: space after colons

oops. fixed in next commit.

koaning · 2018-03-10T19:41:17Z

@TomAugspurger

i made a variable for the docstring
i reordered the docstring -> see also is now below returns
i added a space after the colon #mybad
i confirmed the html still looks good on my end

you can see the new output of the validation script below:

################################################################################
###################### Docstring (pandas.Series.dt.week)  ######################
################################################################################

The week ordinal of the year.

Return the week ordinal of the year. Note that there can be
counter intuitive edge cases around the yearchange. 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

See Also
--------
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")})
          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 what `series.dt.week` and `series.dt.weekofyear` are the same.

>>> 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
0    52
1    52
2     1
3     1
4     1
5     1
6     1
7     1
8     1
dtype: int64

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.Series.dt.week" correct. :)

koaning · 2018-03-10T20:14:14Z

@TomAugspurger should be good to go now.

TomAugspurger

Couple small ones I missed first time around. Ping me here or in chat when you're done.

TomAugspurger · 2018-03-10T20:19:06Z

pandas/core/indexes/datetimes.py

@@ -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 = """


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.

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)

Ah, nvm you're good then.

TomAugspurger · 2018-03-10T20:19:43Z

pandas/core/indexes/datetimes.py

+
+    Returns
+    -------
+    ndarray of integers indicating the week number


I thikn

days : ndarray integers indicating the week number

ndarray is the type, the rest is the ddescription.

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

TomAugspurger · 2018-03-10T20:19:59Z

pandas/core/indexes/datetimes.py

+    7 2017-01-07     1   Saturday
+    8 2017-01-08     1     Sunday
+
+    Note that `series.dt.week` and `series.dt.weekofyear` are the same.


series -> Series

jorisvandenbossche · 2018-03-10T20:24:20Z

General question @TomAugspurger : how do we deal with the fact this is docstring for both DatetimeIndex and Series.dt ?

TomAugspurger · 2018-03-10T20:27:40Z

Good question. How about just noting that "This method is available on both Series with datetime values or DatetimeIndex" in the extended summary?

And then both in the example.

koaning · 2018-03-10T21:17:51Z

@TomAugspurger will add that.

@jorisvandenbossche picking up gitter chat here.

weekofyear = _field_accessor('weekofyear', 'woy', _ weekofyear_doc)
week = weekofyear

Do we want both properties to have the same docstring? If so, do we mind the verbose example that explains you could do both?

TomAugspurger · 2018-03-10T21:41:27Z

I think same docstring is fine.

jreback · 2018-03-10T21:50:03Z

pandas/core/indexes/datetimes.py

+    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. This method is available


can you add a link to wikipedia (I think this goes by common week of year)

jreback · 2018-03-10T21:50:36Z

pandas/core/indexes/datetimes.py

+
+    Returns
+    -------
+    ndarry


this returns an Index

jreback · 2018-03-10T21:50:55Z

pandas/core/indexes/datetimes.py

+    --------
+    >>> 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")})


use s.dt.day_name()

jreback · 2018-03-10T21:51:14Z

pandas/core/indexes/datetimes.py

+    7     1
+    8     1
+    dtype: int64
+    >>> s.dt.weekofyear


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

datapythonista · 2018-11-03T05:45:59Z

Closing as stale. Also, the code this PR is based on does not live there anymore.

koaning added 2 commits March 10, 2018 19:10

added proper example and edge case in docstring

4916ea2

Merge remote-tracking branch 'upstream/master' into DOC-series.dt.wee…

d2b5498

…kofyear

koaning added 3 commits March 10, 2018 20:15

some pep8 fixes

dfd26b3

some pep8 fixes

f461492

E128 still failing. requires advice.

83e03e2

koaning commented Mar 10, 2018

View reviewed changes

wh00ps. wrong return portion

aac1423

TomAugspurger reviewed Mar 10, 2018

View reviewed changes

made changes based on TomAugspurgers review

b5ca86b

spelling

d26938d

TomAugspurger reviewed Mar 10, 2018

View reviewed changes

koaning added 2 commits March 10, 2018 22:31

rewrote return per docs + series to Series

035f1c5

added comment of multiple occurence

ec04a59

jreback requested changes Mar 10, 2018

View reviewed changes

jreback added Docs Datetime Datetime data dtype labels Mar 10, 2018

jorisvandenbossche mentioned this pull request Mar 10, 2018

DOC: find solution for shared docstrings of DatetimeIndex and Series.dt #20258

Open

datapythonista self-assigned this Jul 22, 2018

datapythonista closed this Nov 3, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

koaning commented Mar 10, 2018 •

edited

Loading

pep8speaks commented Mar 10, 2018 •

edited

Loading

koaning commented Mar 10, 2018

koaning Mar 10, 2018

koaning Mar 10, 2018

TomAugspurger Mar 10, 2018

koaning Mar 10, 2018

TomAugspurger Mar 10, 2018

koaning Mar 10, 2018

TomAugspurger Mar 10, 2018

koaning Mar 10, 2018

koaning commented Mar 10, 2018 •

edited

Loading

koaning commented Mar 10, 2018

TomAugspurger left a comment

TomAugspurger Mar 10, 2018

koaning Mar 10, 2018

TomAugspurger Mar 10, 2018

TomAugspurger Mar 10, 2018

koaning Mar 10, 2018

TomAugspurger Mar 10, 2018

koaning Mar 10, 2018

jorisvandenbossche commented Mar 10, 2018

TomAugspurger commented Mar 10, 2018

koaning commented Mar 10, 2018 •

edited

Loading

TomAugspurger commented Mar 10, 2018

jreback Mar 10, 2018

jreback Mar 10, 2018

jreback Mar 10, 2018

jreback Mar 10, 2018

datapythonista commented Nov 3, 2018

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

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

Conversation

koaning commented Mar 10, 2018 • edited Loading

pep8speaks commented Mar 10, 2018 • edited Loading

Comment last updated on March 10, 2018 at 21:39 Hours UTC

koaning commented Mar 10, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

koaning commented Mar 10, 2018 • edited Loading

koaning commented Mar 10, 2018

TomAugspurger left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jorisvandenbossche commented Mar 10, 2018

TomAugspurger commented Mar 10, 2018

koaning commented Mar 10, 2018 • edited Loading

TomAugspurger commented Mar 10, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

datapythonista commented Nov 3, 2018

koaning commented Mar 10, 2018 •

edited

Loading

pep8speaks commented Mar 10, 2018 •

edited

Loading

koaning commented Mar 10, 2018 •

edited

Loading

koaning commented Mar 10, 2018 •

edited

Loading