DOC: update the pandas.DataFrame.any docstring#20217
DOC: update the pandas.DataFrame.any docstring#20217TomAugspurger merged 13 commits intomasterfrom unknown repository
Conversation
There was a problem hiding this comment.
Hmm looks like some extra files were committed. I thikn we have another PR adding savefig to our gitignore.
Can you remove those files rm -rf doc/source/savefig and then update your PR. I thikn with git rm doc/source/savefig.
Reviewers: we should wait for at least one CI to finish since this is changing parameters passed through the functions making the docstrings.
pandas/core/generic.py
Outdated
| _any_also = """\ | ||
| See Also | ||
| -------- | ||
| pandas.DataFrame.all : Return whether all elements are True \ |
There was a problem hiding this comment.
I don't think you need the trailing \ here do you?
There was a problem hiding this comment.
to be clear, you do need the one on the first line, jsut not these.
There was a problem hiding this comment.
yes, and the same for the ones below as well
There was a problem hiding this comment.
@TomAugspurger if I don't put \, line becomes longer than 79 characters and it isn't passing git diff origin/master -u -- "*.py" | flake8 --diff validation...
There was a problem hiding this comment.
We want them, else we get long lines in the text docstring liek
One dimensional boolean pandas.Series is returned. Unlike pandas.DataFrame.all, pandas.DataFrame.any performs OR operation; in other word, if any of the values along the specified axis is True, pandas.DataFrame.any will return True.
There was a problem hiding this comment.
@TomAugspurger & @jorisvandenbossche , let's say I removed \ and , then the result of git diff origin/master -u -- "*.py" | flake8 --diff is going to be pandas/core/generic.py:7834:80: E501 line too long (83 > 79 characters), since the line is pandas.DataFrame.all : Return whether all elements are True over requested axis. - I don't want to break the line with \n, instead, I'm using \. There is exactly same reason behind the cases I used \.
pandas/core/generic.py
Outdated
| _any_examples = """\ | ||
| Examples | ||
| -------- | ||
| By default, any from an empty DataFrame is empty Series:: |
There was a problem hiding this comment.
No double colon, just a .
There was a problem hiding this comment.
@TomAugspurger according to this documentation, double colon is required to show code samples.
pandas/core/generic.py
Outdated
| -------- | ||
| By default, any from an empty DataFrame is empty Series:: | ||
|
|
||
| >> pd.DataFrame([]).any() |
There was a problem hiding this comment.
Three >. Doesn't need to be indented.
There was a problem hiding this comment.
@TomAugspurger , you mean, without double-colon and three >, is it going to show code samples as required?
pandas/core/generic.py
Outdated
|
|
||
| Non-boolean values will always give True:: | ||
|
|
||
| >> pd.DataFrame({"A": [1, 2, 3], "B": [4, 5, 6]}).any() |
pandas/core/generic.py
Outdated
|
|
||
| It is performing OR along the specified axis:: | ||
|
|
||
| >> pd.DataFrame({"A": [1, False, 3], "B": [4, 5, 6]}).any(axis=1) |
pandas/core/generic.py
Outdated
| 2 True | ||
| dtype: bool | ||
|
|
||
| >> pd.DataFrame({"A": [1, False, 3], "B": [4, False, 6]}).any(axis=1) |
jorisvandenbossche
left a comment
There was a problem hiding this comment.
Can you also add an example with Series ? (the docstring is shared for both Series and DataFrame)
pandas/core/generic.py
Outdated
| _any_also = """\ | ||
| See Also | ||
| -------- | ||
| pandas.DataFrame.all : Return whether all elements are True \ |
There was a problem hiding this comment.
yes, and the same for the ones below as well
pandas/core/generic.py
Outdated
| _any_desc = """\ | ||
| Return whether any element is True over requested axis. | ||
|
|
||
| One dimensional pandas.Series having boolean values will be returned. \ |
There was a problem hiding this comment.
pandas.Series -> Series
There was a problem hiding this comment.
I would also say "boolean Series" instead of "Series having boolean values"
pandas/core/generic.py
Outdated
| One dimensional pandas.Series having boolean values will be returned. \ | ||
| Unlike pandas.DataFrame.all, pandas.DataFrame.any performs OR operation; \ | ||
| in other word, if any of the values along the specified axis is True, \ | ||
| pandas.DataFrame.any will return True.""" |
There was a problem hiding this comment.
Can you also mention here something that for Series the return value is a single boolean value?
|
this needs a rebase now |
|
@smusali I'm doing the rebase / merge. 1 minute. |
|
@smusali fixed the merge conflict. Also made an update to the grammar and examples. I changed the examples to have consistent types for the columns. In general, having a mix like |
|
Done some requested changes and made some fixes - please, review, @TomAugspurger, @jreback and @jorisvandenbossche; thanks in advance! |
|
|
@TomAugspurger , do u have any more change request? |
|
Just updated the examples a tad to show the dataframes. |
Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):
scripts/validate_docstrings.py <your-function-or-method>git diff upstream/master -u -- "*.py" | flake8 --diffpython doc/make.py --single <your-function-or-method>Please include the output of the validation script below between the "```" ticks:
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.
Checklist for other PRs (remove this part if you are doing a PR for the pandas documentation sprint):
git diff upstream/master -u -- "*.py" | flake8 --diff