From e828f24af555ce832f84704beefb794169dcc1bd Mon Sep 17 00:00:00 2001 From: Brendan Sullivan Date: Sat, 14 Mar 2020 12:22:41 -0400 Subject: [PATCH 1/4] DOC: add series examples (#24589) adds documentation example to: - `pandas.Series.eq` - `pandas.Series.ne` - `pandas.Series.gt`, - `pandas.Series.ge` - `pandas.series.le` - `pandas.series.lt` --- pandas/core/ops/docstrings.py | 186 ++++++++++++++++++++++++++++++++-- 1 file changed, 180 insertions(+), 6 deletions(-) diff --git a/pandas/core/ops/docstrings.py b/pandas/core/ops/docstrings.py index 203ea3946d1b2..02099444b14b8 100644 --- a/pandas/core/ops/docstrings.py +++ b/pandas/core/ops/docstrings.py @@ -234,6 +234,180 @@ def _make_flex_doc(op_name, typ): dtype: float64 """ +_ne_example_SERIES = """ +Examples +-------- +>>> a = pd.Series([1, 1, np.nan, np.nan, 0], index=['a', 'b', 'c', 'd', 'e']) +>>> a +a 1.0 +b 1.0 +c 1.0 +d NaN +e 1.0 +dtype: float64 +>>> b = pd.Series([0, 1, np.nan, 0, 1], index=['a', 'b', 'c', 'd', 'f']) +>>> b +a 0.0 +b 1.0 +c 2.0 +d NaN +f 1.0 +dtype: float64 +>>> a.ne(b, fill_value=0) +a True +b False +c True +d False +e False +f True +dtype: bool +""" + +_eq_example_SERIES = """ +Examples +-------- +>>> a = pd.Series([1, 1, np.nan, np.nan, 0], index=['a', 'b', 'c', 'd', 'e']) +>>> a +a 1.0 +b 1.0 +c 1.0 +d NaN +e 1.0 +dtype: float64 +>>> b = pd.Series([0, 1, np.nan, 0, 1], index=['a', 'b', 'c', 'd', 'f']) +>>> b +a 0.0 +b 1.0 +c 2.0 +d NaN +f 1.0 +dtype: float64 +>>> a.eq(b, fill_value=0) +a False +b True +c False +d True +e True +f False +dtype: bool +""" + +_lt_example_SERIES = """ +Examples +-------- +>>> a = pd.Series([1, 1, 1, np.nan, 1], index=['a', 'b', 'c', 'd', 'e']) +>>> a +a 1.0 +b 1.0 +c 1.0 +d NaN +e 1.0 +dtype: float64 +>>> b = pd.Series([0, 1, 2, np.nan, 1], index=['a', 'b', 'c', 'd', 'f']) +>>> b +a 0.0 +b 1.0 +c 2.0 +d NaN +f 1.0 +dtype: float64 +>>> a.lt(b, fill_value=0) +a False +b False +c True +d False +e False +f True +dtype: bool +""" + +_le_example_SERIES = """ +Examples +-------- +>>> a = pd.Series([1, 1, 1, np.nan, 1], index=['a', 'b', 'c', 'd', 'e']) +>>> a +a 1.0 +b 1.0 +c 1.0 +d NaN +e 1.0 +dtype: float64 +>>> b = pd.Series([0, 1, 2, np.nan, 1], index=['a', 'b', 'c', 'd', 'f']) +>>> b +a 0.0 +b 1.0 +c 2.0 +d NaN +f 1.0 +dtype: float64 +>>> a.le(b, fill_value=0) +a False +b True +c True +d False +e False +f True +dtype: bool +""" + +_gt_example_SERIES = """ +Examples +-------- +>>> a = pd.Series([1, 1, 1, np.nan, 1], index=['a', 'b', 'c', 'd', 'e']) +>>> a +a 1.0 +b 1.0 +c 1.0 +d NaN +e 1.0 +dtype: float64 +>>> b = pd.Series([0, 1, 2, np.nan, 1], index=['a', 'b', 'c', 'd', 'f']) +>>> b +a 0.0 +b 1.0 +c 2.0 +d NaN +f 1.0 +dtype: float64 +>>> a.gt(b, fill_value=0) +a True +b False +c False +d False +e True +f False +dtype: bool +""" + +_ge_example_SERIES = """ +Examples +-------- +>>> a = pd.Series([1, 1, 1, np.nan, 1], index=['a', 'b', 'c', 'd', 'e']) +>>> a +a 1.0 +b 1.0 +c 1.0 +d NaN +e 1.0 +dtype: float64 +>>> b = pd.Series([0, 1, 2, np.nan, 1], index=['a', 'b', 'c', 'd', 'f']) +>>> b +a 0.0 +b 1.0 +c 2.0 +d NaN +f 1.0 +dtype: float64 +>>> a.ge(b, fill_value=0) +a True +b True +c False +d False +e True +f False +dtype: bool +""" + _returns_series = """Series\n The result of the operation.""" _returns_tuple = """2-Tuple of Series\n The result of the operation.""" @@ -306,42 +480,42 @@ def _make_flex_doc(op_name, typ): "op": "==", "desc": "Equal to", "reverse": None, - "series_examples": None, + "series_examples": _eq_example_SERIES, "series_returns": _returns_series, }, "ne": { "op": "!=", "desc": "Not equal to", "reverse": None, - "series_examples": None, + "series_examples": _ne_example_SERIES, "series_returns": _returns_series, }, "lt": { "op": "<", "desc": "Less than", "reverse": None, - "series_examples": None, + "series_examples": _lt_example_SERIES, "series_returns": _returns_series, }, "le": { "op": "<=", "desc": "Less than or equal to", "reverse": None, - "series_examples": None, + "series_examples": _le_example_SERIES, "series_returns": _returns_series, }, "gt": { "op": ">", "desc": "Greater than", "reverse": None, - "series_examples": None, + "series_examples": _gt_example_SERIES, "series_returns": _returns_series, }, "ge": { "op": ">=", "desc": "Greater than or equal to", "reverse": None, - "series_examples": None, + "series_examples": _ge_example_SERIES, "series_returns": _returns_series, }, } From 926a3cfac146bcfa25d020f25595cae45abd5fb8 Mon Sep 17 00:00:00 2001 From: Brendan Sullivan Date: Sun, 22 Mar 2020 13:26:06 -0400 Subject: [PATCH 2/4] move variable creation to common variable --- pandas/core/ops/docstrings.py | 264 ++++++---------------------------- 1 file changed, 40 insertions(+), 224 deletions(-) diff --git a/pandas/core/ops/docstrings.py b/pandas/core/ops/docstrings.py index 02099444b14b8..6bd99838d9e5e 100644 --- a/pandas/core/ops/docstrings.py +++ b/pandas/core/ops/docstrings.py @@ -53,7 +53,7 @@ def _make_flex_doc(op_name, typ): return doc -_add_example_SERIES = """ +_common_examples_SERIES = """ Examples -------- >>> a = pd.Series([1, 1, 1, np.nan], index=['a', 'b', 'c', 'd']) @@ -69,33 +69,39 @@ def _make_flex_doc(op_name, typ): 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 -""" +dtype: float64""" -_sub_example_SERIES = """ +_common_examples_comparison_SERIES = """ Examples -------- ->>> a = pd.Series([1, 1, 1, np.nan], index=['a', 'b', 'c', 'd']) +>>> a = pd.Series([1, 1, 1, np.nan, 1], index=['a', 'b', 'c', 'd', 'e']) >>> a a 1.0 b 1.0 c 1.0 d NaN +e 1.0 dtype: float64 ->>> b = pd.Series([1, np.nan, 1, np.nan], index=['a', 'b', 'd', 'e']) +>>> b = pd.Series([0, 1, 2, np.nan, 1], index=['a', 'b', 'c', 'd', 'f']) >>> b -a 1.0 -b NaN +a 0.0 +b 1.0 +c 2.0 +d NaN +f 1.0 +dtype: float64""" + +_add_example_SERIES = _common_examples_SERIES + """ +>>> 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 = _common_examples_SERIES + """ >>> a.subtract(b, fill_value=0) a 0.0 b 1.0 @@ -105,23 +111,7 @@ def _make_flex_doc(op_name, typ): 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 +_mul_example_SERIES = _common_examples_SERIES + """ >>> a.multiply(b, fill_value=0) a 1.0 b 0.0 @@ -131,23 +121,7 @@ def _make_flex_doc(op_name, typ): 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 +_div_example_SERIES = _common_examples_SERIES + """ >>> a.divide(b, fill_value=0) a 1.0 b inf @@ -157,23 +131,7 @@ def _make_flex_doc(op_name, typ): 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 +_floordiv_example_SERIES = _common_examples_SERIES + """ >>> a.floordiv(b, fill_value=0) a 1.0 b NaN @@ -183,23 +141,7 @@ def _make_flex_doc(op_name, typ): 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 +_mod_example_SERIES = _common_examples_SERIES + """ >>> a.mod(b, fill_value=0) a 0.0 b NaN @@ -208,23 +150,7 @@ def _make_flex_doc(op_name, typ): 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 +_pow_example_SERIES = _common_examples_SERIES + """ >>> a.pow(b, fill_value=0) a 1.0 b 1.0 @@ -234,83 +160,27 @@ def _make_flex_doc(op_name, typ): dtype: float64 """ -_ne_example_SERIES = """ -Examples --------- ->>> a = pd.Series([1, 1, np.nan, np.nan, 0], index=['a', 'b', 'c', 'd', 'e']) ->>> a -a 1.0 -b 1.0 -c 1.0 -d NaN -e 1.0 -dtype: float64 ->>> b = pd.Series([0, 1, np.nan, 0, 1], index=['a', 'b', 'c', 'd', 'f']) ->>> b -a 0.0 -b 1.0 -c 2.0 -d NaN -f 1.0 -dtype: float64 +_ne_example_SERIES = _common_examples_SERIES + """ >>> a.ne(b, fill_value=0) -a True -b False +a False +b True c True -d False -e False -f True +d True +e True dtype: bool """ -_eq_example_SERIES = """ -Examples --------- ->>> a = pd.Series([1, 1, np.nan, np.nan, 0], index=['a', 'b', 'c', 'd', 'e']) ->>> a -a 1.0 -b 1.0 -c 1.0 -d NaN -e 1.0 -dtype: float64 ->>> b = pd.Series([0, 1, np.nan, 0, 1], index=['a', 'b', 'c', 'd', 'f']) ->>> b -a 0.0 -b 1.0 -c 2.0 -d NaN -f 1.0 -dtype: float64 +_eq_example_SERIES = _common_examples_SERIES + """ >>> a.eq(b, fill_value=0) -a False -b True +a True +b False c False -d True -e True -f False +d False +e False dtype: bool """ -_lt_example_SERIES = """ -Examples --------- ->>> a = pd.Series([1, 1, 1, np.nan, 1], index=['a', 'b', 'c', 'd', 'e']) ->>> a -a 1.0 -b 1.0 -c 1.0 -d NaN -e 1.0 -dtype: float64 ->>> b = pd.Series([0, 1, 2, np.nan, 1], index=['a', 'b', 'c', 'd', 'f']) ->>> b -a 0.0 -b 1.0 -c 2.0 -d NaN -f 1.0 -dtype: float64 +_lt_example_SERIES = _common_examples_comparison_SERIES + """ >>> a.lt(b, fill_value=0) a False b False @@ -321,25 +191,7 @@ def _make_flex_doc(op_name, typ): dtype: bool """ -_le_example_SERIES = """ -Examples --------- ->>> a = pd.Series([1, 1, 1, np.nan, 1], index=['a', 'b', 'c', 'd', 'e']) ->>> a -a 1.0 -b 1.0 -c 1.0 -d NaN -e 1.0 -dtype: float64 ->>> b = pd.Series([0, 1, 2, np.nan, 1], index=['a', 'b', 'c', 'd', 'f']) ->>> b -a 0.0 -b 1.0 -c 2.0 -d NaN -f 1.0 -dtype: float64 +_le_example_SERIES = _common_examples_comparison_SERIES + """ >>> a.le(b, fill_value=0) a False b True @@ -350,25 +202,7 @@ def _make_flex_doc(op_name, typ): dtype: bool """ -_gt_example_SERIES = """ -Examples --------- ->>> a = pd.Series([1, 1, 1, np.nan, 1], index=['a', 'b', 'c', 'd', 'e']) ->>> a -a 1.0 -b 1.0 -c 1.0 -d NaN -e 1.0 -dtype: float64 ->>> b = pd.Series([0, 1, 2, np.nan, 1], index=['a', 'b', 'c', 'd', 'f']) ->>> b -a 0.0 -b 1.0 -c 2.0 -d NaN -f 1.0 -dtype: float64 +_gt_example_SERIES = _common_examples_comparison_SERIES + """ >>> a.gt(b, fill_value=0) a True b False @@ -379,25 +213,7 @@ def _make_flex_doc(op_name, typ): dtype: bool """ -_ge_example_SERIES = """ -Examples --------- ->>> a = pd.Series([1, 1, 1, np.nan, 1], index=['a', 'b', 'c', 'd', 'e']) ->>> a -a 1.0 -b 1.0 -c 1.0 -d NaN -e 1.0 -dtype: float64 ->>> b = pd.Series([0, 1, 2, np.nan, 1], index=['a', 'b', 'c', 'd', 'f']) ->>> b -a 0.0 -b 1.0 -c 2.0 -d NaN -f 1.0 -dtype: float64 +_ge_example_SERIES = _common_examples_comparison_SERIES + """ >>> a.ge(b, fill_value=0) a True b True From 062e99ca2fccc1d898892acbf6c304fd9405b2f3 Mon Sep 17 00:00:00 2001 From: Brendan Sullivan Date: Sun, 22 Mar 2020 14:15:28 -0400 Subject: [PATCH 3/4] pep8 formatting --- pandas/core/ops/docstrings.py | 65 ++++++++++++++++++++++++++++------- 1 file changed, 52 insertions(+), 13 deletions(-) diff --git a/pandas/core/ops/docstrings.py b/pandas/core/ops/docstrings.py index 6bd99838d9e5e..0b860070a7957 100644 --- a/pandas/core/ops/docstrings.py +++ b/pandas/core/ops/docstrings.py @@ -91,7 +91,9 @@ def _make_flex_doc(op_name, typ): f 1.0 dtype: float64""" -_add_example_SERIES = _common_examples_SERIES + """ +_add_example_SERIES = ( + _common_examples_SERIES + + """ >>> a.add(b, fill_value=0) a 2.0 b 1.0 @@ -100,8 +102,11 @@ def _make_flex_doc(op_name, typ): e NaN dtype: float64 """ +) -_sub_example_SERIES = _common_examples_SERIES + """ +_sub_example_SERIES = ( + _common_examples_SERIES + + """ >>> a.subtract(b, fill_value=0) a 0.0 b 1.0 @@ -110,8 +115,11 @@ def _make_flex_doc(op_name, typ): e NaN dtype: float64 """ +) -_mul_example_SERIES = _common_examples_SERIES + """ +_mul_example_SERIES = ( + _common_examples_SERIES + + """ >>> a.multiply(b, fill_value=0) a 1.0 b 0.0 @@ -120,8 +128,11 @@ def _make_flex_doc(op_name, typ): e NaN dtype: float64 """ +) -_div_example_SERIES = _common_examples_SERIES + """ +_div_example_SERIES = ( + _common_examples_SERIES + + """ >>> a.divide(b, fill_value=0) a 1.0 b inf @@ -130,8 +141,11 @@ def _make_flex_doc(op_name, typ): e NaN dtype: float64 """ +) -_floordiv_example_SERIES = _common_examples_SERIES + """ +_floordiv_example_SERIES = ( + _common_examples_SERIES + + """ >>> a.floordiv(b, fill_value=0) a 1.0 b NaN @@ -140,8 +154,11 @@ def _make_flex_doc(op_name, typ): e NaN dtype: float64 """ +) -_mod_example_SERIES = _common_examples_SERIES + """ +_mod_example_SERIES = ( + _common_examples_SERIES + + """ >>> a.mod(b, fill_value=0) a 0.0 b NaN @@ -150,7 +167,10 @@ def _make_flex_doc(op_name, typ): e NaN dtype: float64 """ -_pow_example_SERIES = _common_examples_SERIES + """ +) +_pow_example_SERIES = ( + _common_examples_SERIES + + """ >>> a.pow(b, fill_value=0) a 1.0 b 1.0 @@ -159,8 +179,11 @@ def _make_flex_doc(op_name, typ): e NaN dtype: float64 """ +) -_ne_example_SERIES = _common_examples_SERIES + """ +_ne_example_SERIES = ( + _common_examples_SERIES + + """ >>> a.ne(b, fill_value=0) a False b True @@ -169,8 +192,11 @@ def _make_flex_doc(op_name, typ): e True dtype: bool """ +) -_eq_example_SERIES = _common_examples_SERIES + """ +_eq_example_SERIES = ( + _common_examples_SERIES + + """ >>> a.eq(b, fill_value=0) a True b False @@ -179,8 +205,11 @@ def _make_flex_doc(op_name, typ): e False dtype: bool """ +) -_lt_example_SERIES = _common_examples_comparison_SERIES + """ +_lt_example_SERIES = ( + _common_examples_comparison_SERIES + + """ >>> a.lt(b, fill_value=0) a False b False @@ -190,8 +219,11 @@ def _make_flex_doc(op_name, typ): f True dtype: bool """ +) -_le_example_SERIES = _common_examples_comparison_SERIES + """ +_le_example_SERIES = ( + _common_examples_comparison_SERIES + + """ >>> a.le(b, fill_value=0) a False b True @@ -201,8 +233,11 @@ def _make_flex_doc(op_name, typ): f True dtype: bool """ +) -_gt_example_SERIES = _common_examples_comparison_SERIES + """ +_gt_example_SERIES = ( + _common_examples_comparison_SERIES + + """ >>> a.gt(b, fill_value=0) a True b False @@ -212,8 +247,11 @@ def _make_flex_doc(op_name, typ): f False dtype: bool """ +) -_ge_example_SERIES = _common_examples_comparison_SERIES + """ +_ge_example_SERIES = ( + _common_examples_comparison_SERIES + + """ >>> a.ge(b, fill_value=0) a True b True @@ -223,6 +261,7 @@ def _make_flex_doc(op_name, typ): f False dtype: bool """ +) _returns_series = """Series\n The result of the operation.""" From ca5111b4711243d47a751488ec200e76a2960f44 Mon Sep 17 00:00:00 2001 From: Brendan Sullivan Date: Tue, 24 Mar 2020 06:42:12 -0400 Subject: [PATCH 4/4] rename _common_examples_SERIES reanamed `_common_examples_SERIES` to more descriptive `_common_examples_algebra_SERIES` --- pandas/core/ops/docstrings.py | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/pandas/core/ops/docstrings.py b/pandas/core/ops/docstrings.py index 0b860070a7957..7b03b4b449ea5 100644 --- a/pandas/core/ops/docstrings.py +++ b/pandas/core/ops/docstrings.py @@ -53,7 +53,7 @@ def _make_flex_doc(op_name, typ): return doc -_common_examples_SERIES = """ +_common_examples_algebra_SERIES = """ Examples -------- >>> a = pd.Series([1, 1, 1, np.nan], index=['a', 'b', 'c', 'd']) @@ -92,7 +92,7 @@ def _make_flex_doc(op_name, typ): dtype: float64""" _add_example_SERIES = ( - _common_examples_SERIES + _common_examples_algebra_SERIES + """ >>> a.add(b, fill_value=0) a 2.0 @@ -105,7 +105,7 @@ def _make_flex_doc(op_name, typ): ) _sub_example_SERIES = ( - _common_examples_SERIES + _common_examples_algebra_SERIES + """ >>> a.subtract(b, fill_value=0) a 0.0 @@ -118,7 +118,7 @@ def _make_flex_doc(op_name, typ): ) _mul_example_SERIES = ( - _common_examples_SERIES + _common_examples_algebra_SERIES + """ >>> a.multiply(b, fill_value=0) a 1.0 @@ -131,7 +131,7 @@ def _make_flex_doc(op_name, typ): ) _div_example_SERIES = ( - _common_examples_SERIES + _common_examples_algebra_SERIES + """ >>> a.divide(b, fill_value=0) a 1.0 @@ -144,7 +144,7 @@ def _make_flex_doc(op_name, typ): ) _floordiv_example_SERIES = ( - _common_examples_SERIES + _common_examples_algebra_SERIES + """ >>> a.floordiv(b, fill_value=0) a 1.0 @@ -157,7 +157,7 @@ def _make_flex_doc(op_name, typ): ) _mod_example_SERIES = ( - _common_examples_SERIES + _common_examples_algebra_SERIES + """ >>> a.mod(b, fill_value=0) a 0.0 @@ -169,7 +169,7 @@ def _make_flex_doc(op_name, typ): """ ) _pow_example_SERIES = ( - _common_examples_SERIES + _common_examples_algebra_SERIES + """ >>> a.pow(b, fill_value=0) a 1.0 @@ -182,7 +182,7 @@ def _make_flex_doc(op_name, typ): ) _ne_example_SERIES = ( - _common_examples_SERIES + _common_examples_algebra_SERIES + """ >>> a.ne(b, fill_value=0) a False @@ -195,7 +195,7 @@ def _make_flex_doc(op_name, typ): ) _eq_example_SERIES = ( - _common_examples_SERIES + _common_examples_algebra_SERIES + """ >>> a.eq(b, fill_value=0) a True