DOC: Improved the docstring of Series.any() #20078

FrankDupree · 2018-03-09T14:44:33Z

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

PR title is "DOC: Improved the docstring of Series.any()"
The validation script passes: scripts/validate_docstrings.py Series.any()
The PEP8 style check passes: git diff upstream/master -u -- "*.py" | flake8 --diff
The html version looks good: python doc/make.py --single Series.any()
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.any)  ########################
################################################################################

Return whether any element is True over requested axis.

Returns True if one (or more) elements are non-zero,
not-empty or not-False.

Parameters
----------
axis : {index (0)}
skipna : boolean, default True
    Exclude NA/null values. If an entire row/column is NA, the result
    will be NA.
level : int or level name, default None
    If the axis is a MultiIndex (hierarchical), count along a
    particular level, collapsing into a scalar.
bool_only : boolean, default None
    Include only boolean columns. If None, will attempt to use everything,
    then use only boolean data. Not implemented for Series.
**kwargs : Additional keywords have no effect but might be accepted for
    compatibility with numpy.

Returns
-------
any : scalar or Series (if level specified)

Examples
--------
>>> s1 = pd.Series([1, 2, 3])
>>> s1.any()
True

>>> import numpy as np
>>> s2 = pd.Series([np.NaN, np.NaN, np.NaN])
>>> s2.any()
False

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

Errors found:
        Errors in parameters section
                Parameters {'kwargs'} not documented
                Unknown parameters {'**kwargs'}
                Parameter "axis" has no description
                Parameter "**kwargs" description should start with capital letter
        See Also section not found

Participants of the documentation sprint were told to go ahead with the description of the "**kwargs" parameter.

Parameter "axis" has no description looks like a bug to me. Noticed some other methods show the same validation error. e.g "pandas.Series.mean" throws the same validation error.

Updates

TomAugspurger · 2018-03-09T15:42:26Z

Does this close a specific issue?

TomAugspurger · 2018-03-09T15:43:32Z

pandas/core/generic.py

+
+Examples
+--------
+>>> s1 = pd.Series([1,2,3])


Could you add spaces after the commas here so this is pep8 compliant?

Okay, will do.

TomAugspurger · 2018-03-09T15:45:40Z

pandas/core/generic.py

+>>> s2.any()
+False
+
+>>> s3 = pd.Series([1,2,3,"Hobbit"])


This last one is a bug: #12863 It should return True / False.

I think just remove it for now.

yeah, I sensed it 👍

codecov · 2018-03-09T15:58:35Z

Codecov Report

Merging #20078 into master will increase coverage by 0.02%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master   #20078      +/-   ##
==========================================
+ Coverage    91.7%   91.72%   +0.02%     
==========================================
  Files         150      150              
  Lines       49122    49149      +27     
==========================================
+ Hits        45045    45083      +38     
+ Misses       4077     4066      -11

Flag	Coverage Δ
#multiple	`90.11% <ø> (+0.02%)`	⬆️
#single	`41.85% <ø> (-0.02%)`	⬇️

Impacted Files	Coverage Δ
pandas/core/generic.py	`95.84% <ø> (ø)`	⬆️
pandas/core/groupby.py	`92.14% <0%> (-0.01%)`	⬇️
pandas/io/html.py	`86.6% <0%> (+0.62%)`	⬆️
pandas/plotting/_converter.py	`66.81% <0%> (+1.73%)`	⬆️

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 731d971...680f48c. Read the comment docs.

datapythonista · 2018-03-09T23:54:20Z

@FrankDupree can you please read carefully the doc on how to submit a PR [1], and make sure you do all the steps correctly? You surely missed the point about the title of the PR, and also copying the output of the validate_docstrings.py in the description. Without those, it's difficult to understand what you sent and review it.

Btw, in the description of the PR, the [ ] are checkboxes. You should make sure you completed every listed point, and mark them with an [X], so we know you did.

Thank you!

https://python-sprints.github.io/pandas/guide/pandas_pr.html

toobaz · 2018-03-10T09:25:52Z

Are Parameter "axis" has no description and See Also section not found solved? If yes, could you update the description?

toobaz · 2018-03-10T09:42:10Z

pandas/core/generic.py

 %(desc)s

+Returns True if one (or more) elements are non-zero,
+not-empty or not-False.
+
 Parameters
 ----------
 axis : %(axis_descr)s


Missing description

(never mind)

toobaz · 2018-03-10T10:09:13Z

Please update the description with the validation script output

jreback · 2018-03-10T12:52:53Z

pandas/core/generic.py

 bool_only : boolean, default None
    Include only boolean columns. If None, will attempt to use everything,
    then use only boolean data. Not implemented for Series.
+**kwargs : Additional keywords have no effect but might be accepted for


@datapythonista is this the language generally recommending here?

I didn't see this earlier. I think the description is similar to the ones used in kwargs with similar behavior. But it should go in the next line, as in the other parameters, and in this line simply leave **kwargs

TomAugspurger · 2018-03-14T15:30:46Z

@FrankDupree Some things have changed in master. Can you check if there's anything else to be done?

FrankDupree · 2018-03-14T15:48:53Z

@TomAugspurger I will.

jorisvandenbossche · 2018-03-14T22:25:53Z

So it seems we had a conflicting PR #20217 that implemented DataFrame.any, and since Series and DataFrame share code, this might have been duplicate work .. Sorry about that!

I am going to close this PR, but please check if there is anything in your PR that is not in http://pandas-docs.github.io/pandas-docs-travis/generated/pandas.Series.any.html#pandas.Series.any.
For example, I think it would be good to add an example of what an empty Series returns (Series([]).any()). Feel free to open a PR for that.

FrankDupree added 3 commits March 9, 2018 09:53

Merge pull request #1 from pandas-dev/master

634543f

Updates

Merge remote-tracking branch 'upstream/master' into pandas_series_fix

bb3ba08

DOC: Improved the docstring of pandas.Series.any

8303f97

TomAugspurger reviewed Mar 9, 2018

View reviewed changes

Updates: removed documentation on bug.

8737e31

DOC: Improved the docstring of Series.any()

680f48c

FrankDupree changed the title ~~Pandas series fix~~ DOC: Improved the docstring of Series.any() Mar 10, 2018

toobaz suggested changes Mar 10, 2018

View reviewed changes

jreback approved these changes Mar 10, 2018

View reviewed changes

jreback added the Docs label Mar 10, 2018

jreback added this to the 0.23.0 milestone Mar 10, 2018

jorisvandenbossche closed this Mar 14, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC: Improved the docstring of Series.any() #20078

DOC: Improved the docstring of Series.any() #20078

FrankDupree commented Mar 9, 2018 •

edited

Loading

TomAugspurger commented Mar 9, 2018

TomAugspurger Mar 9, 2018

FrankDupree Mar 9, 2018

FrankDupree Mar 9, 2018

TomAugspurger Mar 9, 2018

FrankDupree Mar 9, 2018

FrankDupree Mar 9, 2018

codecov bot commented Mar 9, 2018 •

edited

Loading

datapythonista commented Mar 9, 2018

toobaz commented Mar 10, 2018

toobaz Mar 10, 2018

toobaz Mar 10, 2018

toobaz commented Mar 10, 2018

jreback Mar 10, 2018

datapythonista Mar 14, 2018

TomAugspurger commented Mar 14, 2018

FrankDupree commented Mar 14, 2018

jorisvandenbossche commented Mar 14, 2018

DOC: Improved the docstring of Series.any() #20078

DOC: Improved the docstring of Series.any() #20078

Conversation

FrankDupree commented Mar 9, 2018 • edited Loading

TomAugspurger commented Mar 9, 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

codecov bot commented Mar 9, 2018 • edited Loading

Codecov Report

datapythonista commented Mar 9, 2018

toobaz commented Mar 10, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

toobaz commented Mar 10, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

TomAugspurger commented Mar 14, 2018

FrankDupree commented Mar 14, 2018

jorisvandenbossche commented Mar 14, 2018

FrankDupree commented Mar 9, 2018 •

edited

Loading

codecov bot commented Mar 9, 2018 •

edited

Loading