Skip to content

DOC: Updating operators docstrings #20415

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

Merged
merged 32 commits into from
Dec 2, 2018
Merged

DOC: Updating operators docstrings #20415

Changes from 6 commits
Commits
Show all changes
32 commits
Select commit Hold shift + click to select a range
acab08e
DOC: Add examples for DataFrame.gt() and DataFrame.ge()
ParfaitG Mar 11, 2018
1818aeb
Merge branch 'master' of github.com:pandas-dev/pandas into docstring_gt
ParfaitG Mar 12, 2018
86cfd56
Updated latest ops.py
ParfaitG Mar 17, 2018
b68b61f
Merge branch 'master' of github.com:pandas-dev/pandas into docstring_gt
ParfaitG Mar 20, 2018
13fed5f
DOC: Add examples to docstring of DataFrame.ge() and .gt()
ParfaitG Mar 20, 2018
8bdbc14
DOC: Add examples to docstring of DataFrame.ge() and .gt()
ParfaitG Mar 20, 2018
4668c5f
DOC: Update ops.py to add docstring, parameters, and examples to comp…
ParfaitG Jul 22, 2018
e6eb9b9
DOC: Update ops.py for operator methods - cleaning up whitespace
ParfaitG Jul 22, 2018
db143c4
DOC: Update ops.py to extend docstrings for comparison methods
ParfaitG Jul 30, 2018
33ff1e4
DOC: Create single, generalized docstring for comparison methods
ParfaitG Aug 5, 2018
e138d92
DOC: Examples and summary updates to comparison operators
ParfaitG Aug 12, 2018
50e9d98
DOC: further update to parameters and examples for comparison methods
ParfaitG Aug 16, 2018
aa016fd
Merge remote-tracking branch 'upstream/master' into docstring_gt
ParfaitG Aug 16, 2018
c2cc037
DOC: Adjusted notes and examples for comparison methods
ParfaitG Aug 17, 2018
644273b
DOC: Adjusted _flex_comp_doc_FRAME assignment logic
ParfaitG Aug 22, 2018
240a502
DOC: Extended arithmetic operator docstring to resemble comparison op…
ParfaitG Aug 23, 2018
bbcdcbe
DOC: Updated df arithmetic operators, extended series arithmetic and …
ParfaitG Aug 24, 2018
a33f003
Revert "DOC: Updated df arithmetic operators, extended series arithme…
ParfaitG Aug 25, 2018
70950c0
DOC: Update DataFrame arithmetic docstring
ParfaitG Aug 25, 2018
6bcb9b9
DOC: Updated examples in arithmetic operators
ParfaitG Sep 25, 2018
e7da1e9
Merge remote-tracking branch 'upstream/master' into docstring_gt
ParfaitG Sep 27, 2018
20cbec1
Merge remote-tracking branch 'upstream/master' into docstring_gt
ParfaitG Sep 27, 2018
722ae81
Updated doctests with core/ops.py
ParfaitG Sep 27, 2018
4580f7a
Resetting doctests and setup files
ParfaitG Sep 28, 2018
49c7b82
Updated arithmetic doctring to use equiv variable
ParfaitG Sep 29, 2018
1e4e450
Remove df_info.txt generated from doctests
ParfaitG Sep 29, 2018
ec71a04
Updated _gen_eval_kwargs docstring in ops.py to avoid pytest skip
ParfaitG Sep 30, 2018
25129ff
Resolve doctest conflict and get latest upstream changes
ParfaitG Oct 13, 2018
d344688
Update docstrings to conform to PEP 8 syntax
ParfaitG Oct 14, 2018
eaaee0d
Slight indentation fixes
ParfaitG Oct 16, 2018
e777e87
DOC: merge with master, resolved conflicts
ParfaitG Nov 24, 2018
6879e89
Merge remote-tracking branch 'upstream/master' into docstring_gt
ParfaitG Dec 2, 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
86 changes: 82 additions & 4 deletions pandas/core/ops.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -397,6 +397,66 @@ def _get_op_name(op, special):
e NaN -2.0
"""

_gt_example_FRAME = """
>>> df1 = pd.DataFrame({'num1': range(1,6),
... 'num2': range(2,11,2),
... 'num3': range(1,20,4)})
>>> df1
num1 num2 num3
0 1 2 1
1 2 4 5
2 3 6 9
3 4 8 13
4 5 10 17
>>> df2 = pd.DataFrame({'num1': range(6,11),
... 'num2': range(1,10,2),
... 'num3': range(1,20,4)})
>>> df2
num1 num2 num3
0 6 1 1
1 7 3 5
2 8 5 9
3 9 7 13
4 10 9 17
>>> df1.gt(df2)
num1 num2 num3
0 False True False
1 False True False
2 False True False
3 False True False
4 False True False
"""

_ge_example_FRAME = """
>>> df1 = pd.DataFrame({'num1': range(1,6),
... 'num2': range(2,11,2),
... 'num3': range(1,20,4)})
>>> df1
num1 num2 num3
0 1 2 1
1 2 4 5
2 3 6 9
3 4 8 13
4 5 10 17
>>> df2 = pd.DataFrame({'num1': range(6,11),
... 'num2': range(1,10,2),
... 'num3': range(1,20,4)})
Copy link
Member

Choose a reason for hiding this comment

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

In case the doc linter cares,about it, add spaces after commas here

Copy link
Member

Choose a reason for hiding this comment

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

Pls add a space after each of the commas in the range calls.

>>> df2
num1 num2 num3
0 6 1 1
1 7 3 5
2 8 5 9
3 9 7 13
4 10 9 17
>>> df1.ge(df2)
num1 num2 num3
0 False True True
1 False True True
2 False True True
3 False True True
4 False True True
"""
Copy link
Member

Choose a reason for hiding this comment

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

I'm not sure if I'm missing something, but is this always the same for all methods? It could go directly to the doctring and not in a separate variable if that's the case. Besides good docstrings, it's good if we keep the code as simple as possible. So we usually leave the same See Also for all methods in this case, even if the method being documented is self referencing.

Also, do you think we can find something less verbose for the descriptions. Something like Compare DataFrames for equality elementwise may be?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Though much of the words are the same, they differ slightly in the middle. Are you advising removing descriptions?

Copy link
Member

Choose a reason for hiding this comment

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

No, what I meant is that if it's possible, it'd be good that each of these descriptions is shorter. Just making them more concise if you find the way.


_op_descriptions = {
# Arithmetic Operators
'add': {'op': '+',
Expand Down Expand Up @@ -452,11 +512,11 @@ def _get_op_name(op, special):
'gt': {'op': '>',
'desc': 'Greater than',
'reverse': None,
'df_examples': None},
'df_examples': _gt_example_FRAME},
'ge': {'op': '>=',
'desc': 'Greater than or equal to',
'reverse': None,
'df_examples': None}}
'df_examples': _ge_example_FRAME}}
Copy link
Member

Choose a reason for hiding this comment

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

Any reason why you chose these two?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

This was part of the Pandas Doc Sprint some months ago. I was tasked with ge/gt functions with teammates handling others. But we can incorporate le/lt and eq/ne pairs with similar set of examples.


_op_names = list(_op_descriptions.keys())
for key in _op_names:
Expand Down Expand Up @@ -582,6 +642,14 @@ def _get_op_name(op, special):
DataFrame.{reverse}
"""

_flex_comp_doc_FRAME = """
Wrapper for flexible comparison methods {name}
Copy link
Member

Choose a reason for hiding this comment

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

This could use a description of what “flexible” means in this context.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

We maintained original text and only added examples. Please advise on text changes.


Examples
--------
{df_examples}
"""

Copy link
Member

Choose a reason for hiding this comment

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

I think we need to explain what's going on here. And I'd probably set company as the index when creating the DataFrame, to avoid adding extra complexity here. I don't think it's a problem for other examples.

The blank line after the docstring is not required.

Copy link
Member

Choose a reason for hiding this comment

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

Has this been resolved?

Copy link
Member

Choose a reason for hiding this comment

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

Can you also add this explanation? So users can understand in an easier way what we are showing here.

_flex_doc_PANEL = """
{desc} of series and other, element-wise (binary operator `{op_name}`).
Equivalent to ``{equiv}``.
Expand Down Expand Up @@ -1546,8 +1614,18 @@ def na_op(x, y):
result = mask_cmp_op(x, y, op, (np.ndarray, ABCSeries))
return result

@Appender('Wrapper for flexible comparison methods {name}'
.format(name=op_name))
doc = ('Wrapper for flexible comparison methods {name}'
.format(name=op_name))

if op_name in _op_descriptions:
op_desc = _op_descriptions[op_name]

if op_desc['df_examples'] is not None:
base_doc = _flex_comp_doc_FRAME
doc = base_doc.format(name=op_name,
df_examples=op_desc['df_examples'])
Copy link
Member

Choose a reason for hiding this comment

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

Pls add a .strip() to op_desc['df_examples']


@Appender(doc)
def f(self, other, axis=default_axis, level=None):

other = _align_method_FRAME(self, other, axis)
Expand Down