Skip to content

DOC: update the pandas.Series.dt.is_leap_year docstring #20150

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.

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 6 commits into from
Mar 17, 2018

Conversation

rok
Copy link
Contributor

@rok rok commented Mar 10, 2018

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

  • [x ] PR title is "DOC: update the docstring"
  • [x ] The validation script passes: scripts/validate_docstrings.py <your-function-or-method>
  • [x ] The PEP8 style check passes: git diff upstream/master -u -- "*.py" | flake8 --diff
  • [x ] The html version looks good: python doc/make.py --single <your-function-or-method>
  • [x ] 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.is_leap_year)  ##################
################################################################################

Return a boolean indicating if the date belongs to a leap year.

A leap year is a year, occurring every four years, which has 366 days
(instead of 365) including 29th of February as an intercalary day.

Returns
-------
is_leap_year : Series of boolean

Examples
--------
>>> import pandas as pd
>>> dates = pd.date_range("2012-01-01", "2015-01-01", freq="Y")
>>> dates_series = pd.Series(dates)
>>> dates_series
0   2012-12-31
1   2013-12-31
2   2014-12-31
dtype: datetime64[ns]
>>> dates_series.dt.is_leap_year
0     True
1    False
2    False
dtype: bool

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

Errors found:
	See Also section not found

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.

See Also is not relevant for this function as there is no other leap year related functions.


Returns
-------
is_leap_year : Series of boolean
Copy link
Contributor

Choose a reason for hiding this comment

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

There's no need to name the return value, only it's type. And it's missing the description.

The documentation of the return is also similar to the parameters. But in this case, no name will be provided, unless the method returns or yields more than one value (a tuple of values).

The parameters are defined by their name, followed by a space, a colon, another space, and the type (or types). Note that the space between the name and the colon is important. Types are not defined for *args and **kwargs, but must be defined for all other parameters. After the parameter definition, it is required to have a line with the parameter description, which is indented, and can have multiple lines. The description must start with a capital letter, and finish with a dot.

"""
Return a boolean indicating if the date belongs to a leap year.

A leap year is a year, occurring every four years, which has 366 days
Copy link
Contributor

Choose a reason for hiding this comment

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

There are exceptions for this four year rule, years divisible by 100 are not leap years except if they are also divisible by 400.
From wiki:
"Every year that is exactly divisible by four is a leap year, except for years that are exactly divisible by 100, but these centurial years are leap years if they are exactly divisible by 400. For example, the years 1700, 1800, and 1900 were not leap years, but the years 1600 and 2000 were."

Examples
--------
>>> import pandas as pd
>>> dates = pd.date_range("2012-01-01", "2015-01-01", freq="Y")
Copy link
Contributor

Choose a reason for hiding this comment

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

no need to import pandas or numpy

@codecov
Copy link

codecov bot commented Mar 10, 2018

Codecov Report

Merging #20150 into master will decrease coverage by 0.07%.
The diff coverage is n/a.

Impacted file tree graph

@@            Coverage Diff             @@
##           master   #20150      +/-   ##
==========================================
- Coverage    91.8%   91.72%   -0.08%     
==========================================
  Files         152      150       -2     
  Lines       49206    49152      -54     
==========================================
- Hits        45172    45086      -86     
- Misses       4034     4066      +32
Flag Coverage Δ
#multiple 90.11% <ø> (-0.08%) ⬇️
#single 41.84% <ø> (-0.01%) ⬇️
Impacted Files Coverage Δ
pandas/core/indexes/datetimes.py 95.64% <ø> (-0.1%) ⬇️
pandas/plotting/_compat.py 62% <0%> (-28.91%) ⬇️
pandas/core/arrays/base.py 74.35% <0%> (-6.29%) ⬇️
pandas/io/html.py 86.6% <0%> (-2.19%) ⬇️
pandas/io/formats/format.py 96.26% <0%> (-1.99%) ⬇️
pandas/core/arrays/categorical.py 95.06% <0%> (-1.16%) ⬇️
pandas/core/dtypes/base.py 91.66% <0%> (-0.23%) ⬇️
pandas/core/indexes/timedeltas.py 91.03% <0%> (-0.2%) ⬇️
pandas/core/reshape/melt.py 97.19% <0%> (-0.15%) ⬇️
... and 28 more

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update e9a6735...132c335. Read the comment docs.

@jorisvandenbossche jorisvandenbossche added this to the 0.23.0 milestone Mar 17, 2018
Copy link
Member

@jorisvandenbossche jorisvandenbossche left a comment

Choose a reason for hiding this comment

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

Made a small edit to make it generic for Index/Series (the docstring is shared between Series.dt and DatetimeIndex)

@jorisvandenbossche jorisvandenbossche merged commit f7a5682 into pandas-dev:master Mar 17, 2018
@jorisvandenbossche
Copy link
Member

Thanks all!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants