From 2f6173c62403a9128c919d2d3e48471473da6979 Mon Sep 17 00:00:00 2001 From: Daniel Lawrence Date: Sun, 3 Mar 2019 17:22:47 +0000 Subject: [PATCH 1/6] DOC:Remove hard-coded examples from _flex_doc_SERIES (#24589) --- pandas/core/ops.py | 184 ++++++++++++++++++++++++++++++++------------- 1 file changed, 130 insertions(+), 54 deletions(-) diff --git a/pandas/core/ops.py b/pandas/core/ops.py index dbdabecafae3a..7d09fabdc01c6 100644 --- a/pandas/core/ops.py +++ b/pandas/core/ops.py @@ -384,57 +384,175 @@ def _get_op_name(op, special): # ----------------------------------------------------------------------------- # Docstring Generation and Templates +_add_example_SERIES = """ +Examples +-------- +>>> a = pd.Series([1, 1, 1, np.nan], index=['a', 'b', 'c', 'd']) +>>> a +a 1.0 +b 1.0 +c 1.0 +d NaN +dtype: float64 +>>> b = pd.Series([1, np.nan, 1, np.nan], index=['a', 'b', 'd', 'e']) +>>> b +a 1.0 +b NaN +d 1.0 +e NaN +dtype: float64 +>>> a.add(b, fill_value=0) +a 2.0 +b 1.0 +c 1.0 +d 1.0 +e NaN +dtype: float64 +""" + +_sub_example_SERIES = """ +Examples +-------- +>>> a = pd.Series([1, 1, 1, np.nan], index=['a', 'b', 'c', 'd']) +>>> a +a 1.0 +b 1.0 +c 1.0 +d NaN +dtype: float64 +>>> b = pd.Series([1, np.nan, 1, np.nan], index=['a', 'b', 'd', 'e']) +>>> b +a 1.0 +b NaN +d 1.0 +e NaN +dtype: float64 +>>> a.subtract(b, fill_value=0) +a 0.0 +b 1.0 +c 1.0 +d -1.0 +e NaN +dtype: float64 +""" + +_mul_example_SERIES = """ +Examples +-------- +>>> a = pd.Series([1, 1, 1, np.nan], index=['a', 'b', 'c', 'd']) +>>> a +a 1.0 +b 1.0 +c 1.0 +d NaN +dtype: float64 +>>> b = pd.Series([1, np.nan, 1, np.nan], index=['a', 'b', 'd', 'e']) +>>> b +a 1.0 +b NaN +d 1.0 +e NaN +dtype: float64 +>>> a.multiply(b) +a 1.0 +b NaN +c NaN +d NaN +e NaN +dtype: float64 +""" + +_div_example_SERIES = """ +Examples +-------- +>>> a = pd.Series([1, 1, 1, np.nan], index=['a', 'b', 'c', 'd']) +>>> a +a 1.0 +b 1.0 +c 1.0 +d NaN +dtype: float64 +>>> b = pd.Series([1, np.nan, 1, np.nan], index=['a', 'b', 'd', 'e']) +>>> b +a 1.0 +b NaN +d 1.0 +e NaN +dtype: float64 +>>> a.divide(b, fill_value=0) +a 1.0 +b inf +c inf +d 0.0 +e NaN +dtype: float64 +""" + _op_descriptions = { # Arithmetic Operators 'add': {'op': '+', 'desc': 'Addition', - 'reverse': 'radd'}, + 'reverse': 'radd', + 'series_examples': _add_example_SERIES}, 'sub': {'op': '-', 'desc': 'Subtraction', - 'reverse': 'rsub'}, + 'reverse': 'rsub', + 'series_examples': _sub_example_SERIES}, 'mul': {'op': '*', 'desc': 'Multiplication', 'reverse': 'rmul', + 'series_examples': _mul_example_SERIES, 'df_examples': None}, 'mod': {'op': '%', 'desc': 'Modulo', - 'reverse': 'rmod'}, + 'reverse': 'rmod', + 'series_examples': None}, 'pow': {'op': '**', 'desc': 'Exponential power', 'reverse': 'rpow', + 'series_examples': None, 'df_examples': None}, 'truediv': {'op': '/', 'desc': 'Floating division', 'reverse': 'rtruediv', + 'series_examples': _div_example_SERIES, 'df_examples': None}, 'floordiv': {'op': '//', 'desc': 'Integer division', 'reverse': 'rfloordiv', + 'series_examples': None, 'df_examples': None}, 'divmod': {'op': 'divmod', 'desc': 'Integer division and modulo', 'reverse': 'rdivmod', + 'series_examples': None, 'df_examples': None}, # Comparison Operators 'eq': {'op': '==', 'desc': 'Equal to', - 'reverse': None}, + 'reverse': None, + 'series_examples': None}, 'ne': {'op': '!=', 'desc': 'Not equal to', - 'reverse': None}, + 'reverse': None, + 'series_examples': None}, 'lt': {'op': '<', 'desc': 'Less than', - 'reverse': None}, + 'reverse': None, + 'series_examples': None}, 'le': {'op': '<=', 'desc': 'Less than or equal to', - 'reverse': None}, + 'reverse': None, + 'series_examples': None}, 'gt': {'op': '>', 'desc': 'Greater than', - 'reverse': None}, + 'reverse': None, + 'series_examples': None}, 'ge': {'op': '>=', 'desc': 'Greater than or equal to', - 'reverse': None} + 'reverse': None, + 'series_examples': None} } _op_names = list(_op_descriptions.keys()) @@ -473,50 +591,7 @@ def _get_op_name(op, special): -------- Series.{reverse} -Examples --------- ->>> a = pd.Series([1, 1, 1, np.nan], index=['a', 'b', 'c', 'd']) ->>> a -a 1.0 -b 1.0 -c 1.0 -d NaN -dtype: float64 ->>> b = pd.Series([1, np.nan, 1, np.nan], index=['a', 'b', 'd', 'e']) ->>> b -a 1.0 -b NaN -d 1.0 -e NaN -dtype: float64 ->>> a.add(b, fill_value=0) -a 2.0 -b 1.0 -c 1.0 -d 1.0 -e NaN -dtype: float64 ->>> a.subtract(b, fill_value=0) -a 0.0 -b 1.0 -c 1.0 -d -1.0 -e NaN -dtype: float64 ->>> a.multiply(b) -a 1.0 -b NaN -c NaN -d NaN -e NaN -dtype: float64 ->>> a.divide(b, fill_value=0) -a 1.0 -b inf -c inf -d 0.0 -e NaN -dtype: float64 +{examples} """ _arith_doc_FRAME = """ @@ -907,7 +982,8 @@ 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']) + equiv=equiv, reverse=op_desc['reverse'], + examples=op_desc['series_examples']) elif typ == 'dataframe': base_doc = _flex_doc_FRAME doc = base_doc.format(desc=op_desc['desc'], op_name=op_name, From 658ea82a3c6dcdd73744bb34b558e2b2c17aa9ce Mon Sep 17 00:00:00 2001 From: Daniel Lawrence Date: Mon, 4 Mar 2019 20:11:09 +0000 Subject: [PATCH 2/6] DOC:Add fill_value to example for SERIES.multiply() (#24589) --- pandas/core/ops.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/pandas/core/ops.py b/pandas/core/ops.py index 7d09fabdc01c6..c2d91dc8d71b1 100644 --- a/pandas/core/ops.py +++ b/pandas/core/ops.py @@ -453,11 +453,11 @@ def _get_op_name(op, special): d 1.0 e NaN dtype: float64 ->>> a.multiply(b) +>>> a.multiply(b, fill_value=0) a 1.0 -b NaN -c NaN -d NaN +b 0.0 +c 0.0 +d 0.0 e NaN dtype: float64 """ From adce62898f06b54331a4fa3711d58c9756482d27 Mon Sep 17 00:00:00 2001 From: Daniel Lawrence Date: Mon, 4 Mar 2019 20:24:00 +0000 Subject: [PATCH 3/6] DOC:Add examples for SERIES ops -- mod,pow,truediv,floordiv (#24589) --- pandas/core/ops.py | 83 ++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 80 insertions(+), 3 deletions(-) diff --git a/pandas/core/ops.py b/pandas/core/ops.py index c2d91dc8d71b1..073cf0b846e46 100644 --- a/pandas/core/ops.py +++ b/pandas/core/ops.py @@ -488,6 +488,83 @@ def _get_op_name(op, special): dtype: float64 """ +_floordiv_example_SERIES = """ +Examples +-------- +>>> a = pd.Series([1, 1, 1, np.nan], index=['a', 'b', 'c', 'd']) +>>> a +a 1.0 +b 1.0 +c 1.0 +d NaN +dtype: float64 +>>> b = pd.Series([1, np.nan, 1, np.nan], index=['a', 'b', 'd', 'e']) +>>> b +a 1.0 +b NaN +d 1.0 +e NaN +dtype: float64 +>>> a.floordiv(b, fill_value=0) +a 1.0 +b NaN +c NaN +d 0.0 +e NaN +dtype: float64 +""" + +_mod_example_SERIES = """ +Examples +-------- +>>> a = pd.Series([1, 1, 1, np.nan], index=['a', 'b', 'c', 'd']) +>>> a +a 1.0 +b 1.0 +c 1.0 +d NaN +dtype: float64 +>>> b = pd.Series([1, np.nan, 1, np.nan], index=['a', 'b', 'd', 'e']) +>>> b +a 1.0 +b NaN +d 1.0 +e NaN +dtype: float64 +>>> a.mod(b, fill_value=0) +a 0.0 +b NaN +c NaN +d 0.0 +e NaN +dtype: float64 +""" +_pow_example_SERIES = """ +Examples +-------- +>>> a = pd.Series([1, 1, 1, np.nan], index=['a', 'b', 'c', 'd']) +>>> a +a 1.0 +b 1.0 +c 1.0 +d NaN +dtype: float64 +>>> b = pd.Series([1, np.nan, 1, np.nan], index=['a', 'b', 'd', 'e']) +>>> b +a 1.0 +b NaN +d 1.0 +e NaN +dtype: float64 +>>> a.pow(b, fill_value=0) +a 1.0 +b 1.0 +c 1.0 +d 0.0 +e NaN +dtype: float64 +""" + _op_descriptions = { # Arithmetic Operators 'add': {'op': '+', @@ -506,11 +583,11 @@ def _get_op_name(op, special): 'mod': {'op': '%', 'desc': 'Modulo', 'reverse': 'rmod', - 'series_examples': None}, + 'series_examples': _mod_example_SERIES}, 'pow': {'op': '**', 'desc': 'Exponential power', 'reverse': 'rpow', - 'series_examples': None, + 'series_examples': _pow_example_SERIES, 'df_examples': None}, 'truediv': {'op': '/', 'desc': 'Floating division', @@ -520,7 +597,7 @@ def _get_op_name(op, special): 'floordiv': {'op': '//', 'desc': 'Integer division', 'reverse': 'rfloordiv', - 'series_examples': None, + 'series_examples': _floordiv_example_SERIES, 'df_examples': None}, 'divmod': {'op': 'divmod', 'desc': 'Integer division and modulo', From fc60c5fddd2c515f64ccce60159c3dd9906d5f51 Mon Sep 17 00:00:00 2001 From: Daniel Lawrence Date: Mon, 4 Mar 2019 20:54:48 +0000 Subject: [PATCH 4/6] DOC:Use string concatenation in _make_flex_doc to appease docstring validator (#24589) --- pandas/core/ops.py | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/pandas/core/ops.py b/pandas/core/ops.py index 073cf0b846e46..7854990385c70 100644 --- a/pandas/core/ops.py +++ b/pandas/core/ops.py @@ -667,8 +667,6 @@ def _get_op_name(op, special): See Also -------- Series.{reverse} - -{examples} """ _arith_doc_FRAME = """ @@ -1058,9 +1056,12 @@ 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'], - examples=op_desc['series_examples']) + doc_no_examples = base_doc.format(desc=op_desc['desc'], op_name=op_name, + equiv=equiv, reverse=op_desc['reverse']) + if op_desc['series_examples']: + doc = doc_no_examples + op_desc['series_examples'] + else: + doc = doc_no_examples elif typ == 'dataframe': base_doc = _flex_doc_FRAME doc = base_doc.format(desc=op_desc['desc'], op_name=op_name, From 74d47c6f132bc80e09d2c1fca4cbe93fe6b2572e Mon Sep 17 00:00:00 2001 From: Daniel Lawrence Date: Mon, 4 Mar 2019 20:58:39 +0000 Subject: [PATCH 5/6] DOC:Fix a long line to satisfy PEP8 (#24589) --- pandas/core/ops.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pandas/core/ops.py b/pandas/core/ops.py index 7854990385c70..fc4a75df0bc29 100644 --- a/pandas/core/ops.py +++ b/pandas/core/ops.py @@ -1056,8 +1056,8 @@ def _make_flex_doc(op_name, typ): if typ == 'series': base_doc = _flex_doc_SERIES - doc_no_examples = base_doc.format(desc=op_desc['desc'], op_name=op_name, - equiv=equiv, reverse=op_desc['reverse']) + doc_no_examples = base_doc.format(desc=op_desc['desc'], + op_name=op_name, equiv=equiv, reverse=op_desc['reverse']) if op_desc['series_examples']: doc = doc_no_examples + op_desc['series_examples'] else: From 6d7ed91ffb1288c3ccea4d69a869e61077ae819e Mon Sep 17 00:00:00 2001 From: Daniel Lawrence Date: Tue, 5 Mar 2019 21:10:22 +0000 Subject: [PATCH 6/6] DOC: break out _make_flex_doc format arguments on seperate lines (#24589) --- pandas/core/ops.py | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/pandas/core/ops.py b/pandas/core/ops.py index fc4a75df0bc29..4d88ce6836ca4 100644 --- a/pandas/core/ops.py +++ b/pandas/core/ops.py @@ -1056,20 +1056,32 @@ def _make_flex_doc(op_name, typ): if typ == 'series': base_doc = _flex_doc_SERIES - doc_no_examples = base_doc.format(desc=op_desc['desc'], - op_name=op_name, equiv=equiv, reverse=op_desc['reverse']) + doc_no_examples = base_doc.format( + desc=op_desc['desc'], + op_name=op_name, + equiv=equiv, + reverse=op_desc['reverse'] + ) if op_desc['series_examples']: doc = doc_no_examples + op_desc['series_examples'] else: doc = doc_no_examples 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']) + doc = base_doc.format( + desc=op_desc['desc'], + op_name=op_name, + equiv=equiv, + reverse=op_desc['reverse'] + ) 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']) + doc = base_doc.format( + desc=op_desc['desc'], + op_name=op_name, + equiv=equiv, + reverse=op_desc['reverse'] + ) else: raise AssertionError('Invalid typ argument.') return doc