From f85e2965bf3136d1800717249c31f894d91f1ab7 Mon Sep 17 00:00:00 2001 From: thoo Date: Sun, 14 Oct 2018 10:15:39 -0400 Subject: [PATCH 1/8] Give Warning on prefix pandas --- scripts/tests/test_validate_docstrings.py | 11 +++++++++++ scripts/validate_docstrings.py | 3 ++- 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/scripts/tests/test_validate_docstrings.py b/scripts/tests/test_validate_docstrings.py index fcae4051dc471..86749236db6bd 100644 --- a/scripts/tests/test_validate_docstrings.py +++ b/scripts/tests/test_validate_docstrings.py @@ -334,6 +334,14 @@ def method(self, foo=None, bar=None): pass +class BadSeeAlso(object): + + def prefix_pandas(self): + """ + Return prefix with `pandas` from See Also sec + """ + pass + class BadSummaries(object): def wrong_line(self): @@ -608,6 +616,9 @@ def test_bad_generic_functions(self, func): assert errors @pytest.mark.parametrize("klass,func,msgs", [ + #SeeAlso tests + ('BadSeeAlso', 'prefix_pandas', + ('Should not start with pandas',)), # Summary tests ('BadSummaries', 'wrong_line', ('should start in the line immediately after the opening quotes',)), diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py index c571827db70f8..c99bf2a04ebff 100755 --- a/scripts/validate_docstrings.py +++ b/scripts/validate_docstrings.py @@ -508,7 +508,8 @@ def validate_one(func_name): if not rel_desc: errs.append('Missing description for ' 'See Also "{}" reference'.format(rel_name)) - + if rel_name[:7].lower() == 'pandas.': + errs.append('{} should not have prefix `pandas`'.format(rel_name)) for line in doc.raw_doc.splitlines(): if re.match("^ *\t", line): errs.append('Tabs found at the start of line "{}", ' From 6a64a629215cba57b25c6d38a1b82507fe67d81b Mon Sep 17 00:00:00 2001 From: thoo Date: Sun, 14 Oct 2018 12:58:25 -0400 Subject: [PATCH 2/8] Update error message and test validator --- scripts/tests/test_validate_docstrings.py | 24 +++++++++++------------ scripts/validate_docstrings.py | 5 +++-- 2 files changed, 14 insertions(+), 15 deletions(-) diff --git a/scripts/tests/test_validate_docstrings.py b/scripts/tests/test_validate_docstrings.py index 86749236db6bd..9c39f90c1d866 100644 --- a/scripts/tests/test_validate_docstrings.py +++ b/scripts/tests/test_validate_docstrings.py @@ -333,15 +333,6 @@ def method(self, foo=None, bar=None): """ pass - -class BadSeeAlso(object): - - def prefix_pandas(self): - """ - Return prefix with `pandas` from See Also sec - """ - pass - class BadSummaries(object): def wrong_line(self): @@ -553,6 +544,13 @@ def no_punctuation(self): """ return "Hello world!" +class BadSeeAlso(object): + + def prefix_pandas(self): + """ + Return prefix with `pandas` from See Also sec + """ + pass class TestValidator(object): @@ -616,9 +614,6 @@ def test_bad_generic_functions(self, func): assert errors @pytest.mark.parametrize("klass,func,msgs", [ - #SeeAlso tests - ('BadSeeAlso', 'prefix_pandas', - ('Should not start with pandas',)), # Summary tests ('BadSummaries', 'wrong_line', ('should start in the line immediately after the opening quotes',)), @@ -667,7 +662,10 @@ def test_bad_generic_functions(self, func): pytest.param('BadReturns', 'no_description', ('foo',), marks=pytest.mark.xfail), pytest.param('BadReturns', 'no_punctuation', ('foo',), - marks=pytest.mark.xfail) + marks=pytest.mark.xfail), + # SeeAlso tests + ('BadSeeAlso', 'prefix_pandas', + ('Should not start with pandas',)), ]) def test_bad_examples(self, capsys, klass, func, msgs): result = validate_one(self._import_path(klass=klass, func=func)) # noqa:F821 diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py index c99bf2a04ebff..4faf576cf4fcc 100755 --- a/scripts/validate_docstrings.py +++ b/scripts/validate_docstrings.py @@ -508,8 +508,9 @@ def validate_one(func_name): if not rel_desc: errs.append('Missing description for ' 'See Also "{}" reference'.format(rel_name)) - if rel_name[:7].lower() == 'pandas.': - errs.append('{} should not have prefix `pandas`'.format(rel_name)) + if rel_name.startswith('pandas.'): + errs.append('{} in the `See Also` section does not need the `pandas` prefix, ' + 'use {} instead.'.format(rel_name,rel_name.replace('pandas.',''))) for line in doc.raw_doc.splitlines(): if re.match("^ *\t", line): errs.append('Tabs found at the start of line "{}", ' From 9358fae103078eeed73df9d4c631dcab70240011 Mon Sep 17 00:00:00 2001 From: thoo Date: Sun, 14 Oct 2018 19:27:38 -0400 Subject: [PATCH 3/8] Fix string prasing and test validator --- scripts/tests/test_validate_docstrings.py | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/scripts/tests/test_validate_docstrings.py b/scripts/tests/test_validate_docstrings.py index 9c39f90c1d866..e94d6690628cc 100644 --- a/scripts/tests/test_validate_docstrings.py +++ b/scripts/tests/test_validate_docstrings.py @@ -549,6 +549,10 @@ class BadSeeAlso(object): def prefix_pandas(self): """ Return prefix with `pandas` from See Also sec + + See Also + -------- + pandas.Series.rename : Alter Series index labels or name """ pass @@ -665,7 +669,7 @@ def test_bad_generic_functions(self, func): marks=pytest.mark.xfail), # SeeAlso tests ('BadSeeAlso', 'prefix_pandas', - ('Should not start with pandas',)), + ('section does not need the `pandas` prefix',)), ]) def test_bad_examples(self, capsys, klass, func, msgs): result = validate_one(self._import_path(klass=klass, func=func)) # noqa:F821 From 4cf7e1be7d61429daa9342bb863d9e26128979df Mon Sep 17 00:00:00 2001 From: thoo Date: Sun, 14 Oct 2018 21:07:13 -0400 Subject: [PATCH 4/8] PEP8 compliant fixes --- scripts/tests/test_validate_docstrings.py | 5 ++++- scripts/validate_docstrings.py | 5 +++-- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/scripts/tests/test_validate_docstrings.py b/scripts/tests/test_validate_docstrings.py index e94d6690628cc..6a648ceb8fd7e 100644 --- a/scripts/tests/test_validate_docstrings.py +++ b/scripts/tests/test_validate_docstrings.py @@ -333,6 +333,7 @@ def method(self, foo=None, bar=None): """ pass + class BadSummaries(object): def wrong_line(self): @@ -544,6 +545,7 @@ def no_punctuation(self): """ return "Hello world!" + class BadSeeAlso(object): def prefix_pandas(self): @@ -556,6 +558,7 @@ def prefix_pandas(self): """ pass + class TestValidator(object): def _import_path(self, klass=None, func=None): @@ -669,7 +672,7 @@ def test_bad_generic_functions(self, func): marks=pytest.mark.xfail), # SeeAlso tests ('BadSeeAlso', 'prefix_pandas', - ('section does not need the `pandas` prefix',)), + ('section does not need `pandas` prefix',)), ]) def test_bad_examples(self, capsys, klass, func, msgs): result = validate_one(self._import_path(klass=klass, func=func)) # noqa:F821 diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py index 4faf576cf4fcc..9517cedd88733 100755 --- a/scripts/validate_docstrings.py +++ b/scripts/validate_docstrings.py @@ -509,8 +509,9 @@ def validate_one(func_name): errs.append('Missing description for ' 'See Also "{}" reference'.format(rel_name)) if rel_name.startswith('pandas.'): - errs.append('{} in the `See Also` section does not need the `pandas` prefix, ' - 'use {} instead.'.format(rel_name,rel_name.replace('pandas.',''))) + errs.append('{} in `See Also` section does not ' + 'need `pandas` prefix, use {} instead.' + .format(rel_name, rel_name.replace('pandas.', ''))) for line in doc.raw_doc.splitlines(): if re.match("^ *\t", line): errs.append('Tabs found at the start of line "{}", ' From 785a7c0597791fe1ee35bb25722ad5a9bdb36e9a Mon Sep 17 00:00:00 2001 From: thoo Date: Mon, 15 Oct 2018 12:02:44 -0400 Subject: [PATCH 5/8] Fix in prefix_pandas and mark.parameterize --- scripts/tests/test_validate_docstrings.py | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/scripts/tests/test_validate_docstrings.py b/scripts/tests/test_validate_docstrings.py index 6a648ceb8fd7e..bde414795425c 100644 --- a/scripts/tests/test_validate_docstrings.py +++ b/scripts/tests/test_validate_docstrings.py @@ -550,11 +550,12 @@ class BadSeeAlso(object): def prefix_pandas(self): """ - Return prefix with `pandas` from See Also sec + Have `pandas` prefix in See Also section. See Also -------- - pandas.Series.rename : Alter Series index labels or name + pandas.Series.rename : Alter Series index labels or name. + DataFrame.head : The first `n` rows of the caller object. """ pass @@ -670,9 +671,9 @@ def test_bad_generic_functions(self, func): marks=pytest.mark.xfail), pytest.param('BadReturns', 'no_punctuation', ('foo',), marks=pytest.mark.xfail), - # SeeAlso tests + # See Also tests ('BadSeeAlso', 'prefix_pandas', - ('section does not need `pandas` prefix',)), + ('pandas.Series.rename in `See Also` section does not need `pandas` prefix',)), ]) def test_bad_examples(self, capsys, klass, func, msgs): result = validate_one(self._import_path(klass=klass, func=func)) # noqa:F821 From 020943080544fcba6a0b4dbf81ef06161170e75f Mon Sep 17 00:00:00 2001 From: thoo Date: Mon, 15 Oct 2018 13:29:03 -0400 Subject: [PATCH 6/8] Fix long string and remove a misplaced comma --- scripts/tests/test_validate_docstrings.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/scripts/tests/test_validate_docstrings.py b/scripts/tests/test_validate_docstrings.py index bde414795425c..04cc713ae201f 100644 --- a/scripts/tests/test_validate_docstrings.py +++ b/scripts/tests/test_validate_docstrings.py @@ -673,7 +673,8 @@ def test_bad_generic_functions(self, func): marks=pytest.mark.xfail), # See Also tests ('BadSeeAlso', 'prefix_pandas', - ('pandas.Series.rename in `See Also` section does not need `pandas` prefix',)), + ('pandas.Series.rename in `See Also` section ' + 'does not need `pandas` prefix',)) ]) def test_bad_examples(self, capsys, klass, func, msgs): result = validate_one(self._import_path(klass=klass, func=func)) # noqa:F821 From 67ed7f46e5b9106ed07c8504d6715faf32edf5d1 Mon Sep 17 00:00:00 2001 From: thoo Date: Wed, 24 Oct 2018 12:44:56 -0400 Subject: [PATCH 7/8] Made changes as recommended --- scripts/validate_docstrings.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py index 9517cedd88733..f3a82097100a9 100755 --- a/scripts/validate_docstrings.py +++ b/scripts/validate_docstrings.py @@ -511,7 +511,7 @@ def validate_one(func_name): if rel_name.startswith('pandas.'): errs.append('{} in `See Also` section does not ' 'need `pandas` prefix, use {} instead.' - .format(rel_name, rel_name.replace('pandas.', ''))) + .format(rel_name, rel_name[len('pandas.'):])) for line in doc.raw_doc.splitlines(): if re.match("^ *\t", line): errs.append('Tabs found at the start of line "{}", ' From 0461c994a755a407917a7a2a75362d1e80737dc6 Mon Sep 17 00:00:00 2001 From: thoo Date: Sat, 27 Oct 2018 01:28:41 -0400 Subject: [PATCH 8/8] modify due to merge with upstream/master --- scripts/tests/test_validate_docstrings.py | 51 +++++++++++------------ 1 file changed, 24 insertions(+), 27 deletions(-) diff --git a/scripts/tests/test_validate_docstrings.py b/scripts/tests/test_validate_docstrings.py index d9d5b6d34befe..0e10265a7291d 100644 --- a/scripts/tests/test_validate_docstrings.py +++ b/scripts/tests/test_validate_docstrings.py @@ -334,33 +334,6 @@ def method(self, foo=None, bar=None): pass -class BadSeeAlso(object): - - def desc_no_period(self): - """ - Return the first 5 elements of the Series. - - See Also - -------- - Series.tail : Return the last 5 elements of the Series. - Series.iloc : Return a slice of the elements in the Series, - which can also be used to return the first or last n - """ - pass - - def desc_first_letter_lowercase(self): - """ - Return the first 5 elements of the Series. - - See Also - -------- - Series.tail : return the last 5 elements of the Series. - Series.iloc : Return a slice of the elements in the Series, - which can also be used to return the first or last n. - """ - pass - - class BadSummaries(object): def wrong_line(self): @@ -575,6 +548,30 @@ def no_punctuation(self): class BadSeeAlso(object): + def desc_no_period(self): + """ + Return the first 5 elements of the Series. + + See Also + -------- + Series.tail : Return the last 5 elements of the Series. + Series.iloc : Return a slice of the elements in the Series, + which can also be used to return the first or last n + """ + pass + + def desc_first_letter_lowercase(self): + """ + Return the first 5 elements of the Series. + + See Also + -------- + Series.tail : return the last 5 elements of the Series. + Series.iloc : Return a slice of the elements in the Series, + which can also be used to return the first or last n. + """ + pass + def prefix_pandas(self): """ Have `pandas` prefix in See Also section.