From 1f7f9b846cdf6f35b19d080a32a331764c5d615c Mon Sep 17 00:00:00 2001 From: aqurilla Date: Sun, 9 Dec 2018 17:28:16 -0500 Subject: [PATCH 1/6] DOC: Fix GH24143 --- pandas/core/indexes/base.py | 6 +++--- pandas/core/indexes/multi.py | 4 ++-- pandas/core/series.py | 6 +++--- pandas/io/stata.py | 4 ++-- scripts/tests/test_validate_docstrings.py | 16 ++++++++++++++++ scripts/validate_docstrings.py | 6 ++++++ 6 files changed, 32 insertions(+), 10 deletions(-) diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index fc5f6758f9e06..3ca8e7e88589b 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -2110,12 +2110,12 @@ def get_duplicates(self): """ Extract duplicated index elements. - Returns a sorted list of index elements which appear more than once in - the index. - .. deprecated:: 0.23.0 Use idx[idx.duplicated()].unique() instead + Returns a sorted list of index elements which appear more than once in + the index. + Returns ------- array-like diff --git a/pandas/core/indexes/multi.py b/pandas/core/indexes/multi.py index be0856e1a825a..86ef3695ee292 100644 --- a/pandas/core/indexes/multi.py +++ b/pandas/core/indexes/multi.py @@ -1484,11 +1484,11 @@ def to_hierarchical(self, n_repeat, n_shuffle=1): Return a MultiIndex reshaped to conform to the shapes given by n_repeat and n_shuffle. + .. deprecated:: 0.24.0 + Useful to replicate and rearrange a MultiIndex for combination with another Index with n_repeat items. - .. deprecated:: 0.24.0 - Parameters ---------- n_repeat : int diff --git a/pandas/core/series.py b/pandas/core/series.py index 4f9465354a47b..a3b8f15664f36 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -1082,12 +1082,12 @@ def set_value(self, label, value, takeable=False): """ Quickly set single value at passed label. - If label is not contained, a new object is created with the label - placed at the end of the result index. - .. deprecated:: 0.21.0 Please use .at[] or .iat[] accessors. + If label is not contained, a new object is created with the label + placed at the end of the result index. + Parameters ---------- label : object diff --git a/pandas/io/stata.py b/pandas/io/stata.py index 403137b695cb7..aadb9686bc6d9 100644 --- a/pandas/io/stata.py +++ b/pandas/io/stata.py @@ -119,8 +119,8 @@ _data_method_doc = """\ Reads observations from Stata file, converting them into a dataframe - .. deprecated:: - This is a legacy method. Use `read` in new code. +.. deprecated:: + This is a legacy method. Use `read` in new code. Parameters ---------- diff --git a/scripts/tests/test_validate_docstrings.py b/scripts/tests/test_validate_docstrings.py index 0c88b7f684c49..61ee86028a7fd 100644 --- a/scripts/tests/test_validate_docstrings.py +++ b/scripts/tests/test_validate_docstrings.py @@ -407,6 +407,20 @@ def sections_in_wrong_order(self): before Examples. """ + def deprecation_in_wrong_order(self): + """ + This is what old method does. + + This is an extended summary with more details about + what `some_old_method` does. + + The extended summary can contain multiple paragraphs. + + .. deprecated:: 1.0 + This should generate an error as it needs to go before + extended summary. + """ + def method_wo_docstrings(self): pass @@ -772,6 +786,8 @@ def test_bad_generic_functions(self, func): ('BadGenericDocStrings', 'sections_in_wrong_order', ('Sections are in the wrong order. Correct order is: Parameters, ' 'See Also, Examples',)), + ('BadGenericDocStrings', 'deprecation_in_wrong_order', + ('Deprecation warning should precede extended summary',)), ('BadSeeAlso', 'desc_no_period', ('Missing period at end of description for See Also "Series.iloc"',)), ('BadSeeAlso', 'desc_first_letter_lowercase', diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py index 0f553cc4f2fe8..2c8e284780623 100755 --- a/scripts/validate_docstrings.py +++ b/scripts/validate_docstrings.py @@ -79,6 +79,7 @@ 'GL07': 'Sections are in the wrong order. Correct order is: ' '{correct_sections}', 'GL08': 'The object does not have a docstring', + 'GL09': 'Deprecation warning should precede extended summary', 'SS01': 'No summary found (a short summary in a single line should be ' 'present at the beginning of the docstring)', 'SS02': 'Summary does not start with a capital letter', @@ -624,6 +625,10 @@ def get_validation_data(doc): errs.append(error('GL07', correct_sections=', '.join(correct_order))) + if (doc.deprecated and not doc.name.startswith('pandas.Panel') + and not doc.extended_summary.startswith('.. deprecated:: ')): + errs.append(error('GL09')) + if not doc.summary: errs.append(error('SS01')) else: @@ -857,6 +862,7 @@ def header(title, width=80, char='#'): else: result = validate_one(func_name) + sys.stderr.write(header('Docstring ({})'.format(func_name))) sys.stderr.write('{}\n'.format(result['docstring'])) sys.stderr.write(header('Validation')) From 0388292240723f48ec955c40977f673d86045de3 Mon Sep 17 00:00:00 2001 From: aqurilla Date: Sun, 9 Dec 2018 17:38:18 -0500 Subject: [PATCH 2/6] DOC: Fix GH24143, updated generic.py --- pandas/core/generic.py | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 1e26c3f45f660..74e65fcf66aef 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -10034,9 +10034,7 @@ def nanptp(values, axis=0, skipna=True): cls, 'ptp', name, name2, axis_descr, """Returns the difference between the maximum value and the minimum value in the object. This is the equivalent of the - ``numpy.ndarray`` method ``ptp``. - - .. deprecated:: 0.24.0 + ``numpy.ndarray`` method ``ptp``.\n\n.. deprecated:: 0.24.0 Use numpy.ptp instead""", nanptp) From 3950b3c9f76ed18b225ff90e4444f38c95b8c539 Mon Sep 17 00:00:00 2001 From: aqurilla Date: Sun, 9 Dec 2018 18:13:46 -0500 Subject: [PATCH 3/6] Updated code_checks.sh --- ci/code_checks.sh | 4 ++-- scripts/validate_docstrings.py | 1 - 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/ci/code_checks.sh b/ci/code_checks.sh index 8462d9ad83431..5b2411ddab6fd 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -209,8 +209,8 @@ fi ### DOCSTRINGS ### if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then - MSG='Validate docstrings (GL06, SS04, PR03, PR05, EX04)' ; echo $MSG - $BASE_DIR/scripts/validate_docstrings.py --format=azure --errors=GL06,SS04,PR03,PR05,EX04 + MSG='Validate docstrings (GL09, GL06, SS04, PR03, PR05, EX04)' ; echo $MSG + $BASE_DIR/scripts/validate_docstrings.py --format=azure --errors=GL09,GL06,SS04,PR03,PR05,EX04 RET=$(($RET + $?)) ; echo $MSG "DONE" fi diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py index 2c8e284780623..bf0eb0457decd 100755 --- a/scripts/validate_docstrings.py +++ b/scripts/validate_docstrings.py @@ -862,7 +862,6 @@ def header(title, width=80, char='#'): else: result = validate_one(func_name) - sys.stderr.write(header('Docstring ({})'.format(func_name))) sys.stderr.write('{}\n'.format(result['docstring'])) sys.stderr.write(header('Validation')) From dae5a7601137adc796b654d2bf83a10286f8b035 Mon Sep 17 00:00:00 2001 From: aqurilla Date: Sun, 9 Dec 2018 19:35:18 -0500 Subject: [PATCH 4/6] Removed hardcoded 'pandas.Panel' check, changed description in test file --- scripts/tests/test_validate_docstrings.py | 8 +++----- scripts/validate_docstrings.py | 8 +++++--- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/scripts/tests/test_validate_docstrings.py b/scripts/tests/test_validate_docstrings.py index 61ee86028a7fd..ca09cbb23d145 100644 --- a/scripts/tests/test_validate_docstrings.py +++ b/scripts/tests/test_validate_docstrings.py @@ -409,12 +409,10 @@ def sections_in_wrong_order(self): def deprecation_in_wrong_order(self): """ - This is what old method does. + This docstring has the deprecation warning in the wrong order. - This is an extended summary with more details about - what `some_old_method` does. - - The extended summary can contain multiple paragraphs. + This is the extended summary. The correct order should be + summary, deprecation warning, extended summary. .. deprecated:: 1.0 This should generate an error as it needs to go before diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py index bf0eb0457decd..77f63cd84b26c 100755 --- a/scripts/validate_docstrings.py +++ b/scripts/validate_docstrings.py @@ -625,9 +625,11 @@ def get_validation_data(doc): errs.append(error('GL07', correct_sections=', '.join(correct_order))) - if (doc.deprecated and not doc.name.startswith('pandas.Panel') - and not doc.extended_summary.startswith('.. deprecated:: ')): - errs.append(error('GL09')) + pattern = re.compile('.. deprecated:: ') + if (bool(pattern.search(doc.summary)) + or bool(pattern.search(doc.extended_summary))): + if not doc.extended_summary.startswith('.. deprecated:: '): + errs.append(error('GL09')) if not doc.summary: errs.append(error('SS01')) From 470f26524f081e13dd171e64d15bfe83919714c6 Mon Sep 17 00:00:00 2001 From: aqurilla Date: Sun, 9 Dec 2018 20:45:22 -0500 Subject: [PATCH 5/6] added property deprecated_with_directive --- scripts/validate_docstrings.py | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py index 77f63cd84b26c..65b33c9616062 100755 --- a/scripts/validate_docstrings.py +++ b/scripts/validate_docstrings.py @@ -492,12 +492,14 @@ def first_line_ends_in_dot(self): if self.doc: return self.doc.split('\n')[0][-1] == '.' + @property + def deprecated_with_directive(self): + return ('.. deprecated:: ' in (self.summary + self.extended_summary)) + @property def deprecated(self): - pattern = re.compile('.. deprecated:: ') return (self.name.startswith('pandas.Panel') - or bool(pattern.search(self.summary)) - or bool(pattern.search(self.extended_summary))) + or self.deprecated_with_directive) @property def mentioned_private_classes(self): @@ -625,11 +627,9 @@ def get_validation_data(doc): errs.append(error('GL07', correct_sections=', '.join(correct_order))) - pattern = re.compile('.. deprecated:: ') - if (bool(pattern.search(doc.summary)) - or bool(pattern.search(doc.extended_summary))): - if not doc.extended_summary.startswith('.. deprecated:: '): - errs.append(error('GL09')) + if (doc.deprecated_with_directive + and not doc.extended_summary.startswith('.. deprecated:: ')): + errs.append(error('GL09')) if not doc.summary: errs.append(error('SS01')) From 5599343fc2108fc2973717a4f656fa55aeeea5fe Mon Sep 17 00:00:00 2001 From: aqurilla Date: Fri, 14 Dec 2018 11:33:59 -0500 Subject: [PATCH 6/6] Merged from PR24215 --- 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 9a9c25df4acd4..2baac5f2c7e31 100755 --- a/scripts/validate_docstrings.py +++ b/scripts/validate_docstrings.py @@ -495,7 +495,7 @@ def first_line_ends_in_dot(self): @property def deprecated_with_directive(self): - return ('.. deprecated:: ' in (self.summary + self.extended_summary)) + return '.. deprecated:: ' in (self.summary + self.extended_summary) @property def deprecated(self):