Skip to content
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

DOC: update pandas/core/ops.py docstring template to accept examples #20246

Merged
merged 2 commits into from
Mar 11, 2018
Merged

DOC: update pandas/core/ops.py docstring template to accept examples #20246

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7795e6c
add hook to include dataframe examples
alysivji Mar 10, 2018
4e3f1ce
change name
jorisvandenbossche Mar 11, 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
117 changes: 71 additions & 46 deletions pandas/core/ops.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -343,50 +343,93 @@ def _get_op_name(op, special):
# -----------------------------------------------------------------------------
# Docstring Generation and Templates

_add_example_FRAME = """
>>> a = pd.DataFrame([1, 1, 1, np.nan], index=['a', 'b', 'c', 'd'],
columns=['one'])
>>> a
one
a 1.0
b 1.0
c 1.0
d NaN
>>> b = pd.DataFrame(dict(one=[1, np.nan, 1, np.nan],
Copy link
Contributor

Choose a reason for hiding this comment

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

blank line between ases

Copy link

Choose a reason for hiding this comment

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

@jreback I am about to put in a PR for one of the examples. Where should there be a blank line? Between what would be "cell" executions?

Copy link
Member

Choose a reason for hiding this comment

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

@kurtiskerstein I think there should be only blank lines around "blocks" of code that you want to have appear together in one code block

two=[np.nan, 2, np.nan, 2]),
index=['a', 'b', 'd', 'e'])
>>> b
one two
a 1.0 NaN
b NaN 2.0
d 1.0 NaN
e NaN 2.0
>>> a.add(b, fill_value=0)
Copy link
Contributor

Choose a reason for hiding this comment

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

could add some text here to indicate what the filling is doing

one two
a 2.0 NaN
b 1.0 2.0
c 1.0 NaN
d 1.0 NaN
e NaN 2.0
"""

_op_descriptions = {
# Arithmetic Operators
'add': {'op': '+',
'desc': 'Addition',
'reverse': 'radd'},
'reverse': 'radd',
'df_examples': _add_example_FRAME},
'sub': {'op': '-',
'desc': 'Subtraction',
'reverse': 'rsub'},
'reverse': 'rsub',
'df_examples': None},
'mul': {'op': '*',
'desc': 'Multiplication',
'reverse': 'rmul'},
'reverse': 'rmul',
'df_examples': None},
'mod': {'op': '%',
'desc': 'Modulo',
'reverse': 'rmod'},
'reverse': 'rmod',
'df_examples': None},
'pow': {'op': '**',
'desc': 'Exponential power',
'reverse': 'rpow'},
'reverse': 'rpow',
'df_examples': None},
'truediv': {'op': '/',
'desc': 'Floating division',
'reverse': 'rtruediv'},
'reverse': 'rtruediv',
'df_examples': None},
'floordiv': {'op': '//',
'desc': 'Integer division',
'reverse': 'rfloordiv'},
'reverse': 'rfloordiv',
'df_examples': None},
'divmod': {'op': 'divmod',
'desc': 'Integer division and modulo',
'reverse': None},
'reverse': None,
'df_examples': None},

# Comparison Operators
'eq': {'op': '==',
'desc': 'Equal to',
'reverse': None},
'desc': 'Equal to',
'reverse': None,
'df_examples': None},
'ne': {'op': '!=',
'desc': 'Not equal to',
'reverse': None},
'desc': 'Not equal to',
'reverse': None,
'df_examples': None},
'lt': {'op': '<',
'desc': 'Less than',
'reverse': None},
'desc': 'Less than',
'reverse': None,
'df_examples': None},
'le': {'op': '<=',
'desc': 'Less than or equal to',
'reverse': None},
'desc': 'Less than or equal to',
'reverse': None,
'df_examples': None},
'gt': {'op': '>',
'desc': 'Greater than',
'reverse': None},
'desc': 'Greater than',
'reverse': None,
'df_examples': None},
'ge': {'op': '>=',
'desc': 'Greater than or equal to',
'reverse': None}}
'desc': 'Greater than or equal to',
'reverse': None,
'df_examples': None}}

_op_names = list(_op_descriptions.keys())
for key in _op_names:
Expand Down Expand Up @@ -532,30 +575,7 @@ def _get_op_name(op, special):

Examples
--------
>>> a = pd.DataFrame([1, 1, 1, np.nan], index=['a', 'b', 'c', 'd'],
columns=['one'])
>>> a
one
a 1.0
b 1.0
c 1.0
d NaN
>>> b = pd.DataFrame(dict(one=[1, np.nan, 1, np.nan],
two=[np.nan, 2, np.nan, 2]),
index=['a', 'b', 'd', 'e'])
>>> b
one two
a 1.0 NaN
b NaN 2.0
d 1.0 NaN
e NaN 2.0
>>> a.add(b, fill_value=0)
one two
a 2.0 NaN
b 1.0 2.0
c 1.0 NaN
d 1.0 NaN
e NaN 2.0
{df_examples}

See also
--------
Expand Down Expand Up @@ -622,14 +642,19 @@ def _make_flex_doc(op_name, typ):

if typ == 'series':
base_doc = _flex_doc_SERIES
doc = base_doc.format(desc=op_desc['desc'], op_name=op_name,
equiv=equiv, reverse=op_desc['reverse'])
elif typ == 'dataframe':
base_doc = _flex_doc_FRAME
doc = base_doc.format(desc=op_desc['desc'], op_name=op_name,
equiv=equiv, reverse=op_desc['reverse'],
df_examples=op_desc['df_examples'])
elif typ == 'panel':
base_doc = _flex_doc_PANEL
doc = base_doc.format(desc=op_desc['desc'], op_name=op_name,
equiv=equiv, reverse=op_desc['reverse'])
else:
raise AssertionError('Invalid typ argument.')
doc = base_doc.format(desc=op_desc['desc'], op_name=op_name,
equiv=equiv, reverse=op_desc['reverse'])
return doc


Expand Down