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/pandas/core/generic.py b/pandas/core/generic.py index 11d1333851794..0df4a067dda44 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -10039,9 +10039,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) diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index 63c0827cccb82..cc6f182fadce6 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -2113,12 +2113,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 f9c9c3ab81937..9ba9cdc818a5e 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -1083,12 +1083,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..ca09cbb23d145 100644 --- a/scripts/tests/test_validate_docstrings.py +++ b/scripts/tests/test_validate_docstrings.py @@ -407,6 +407,18 @@ def sections_in_wrong_order(self): before Examples. """ + def deprecation_in_wrong_order(self): + """ + This docstring has the deprecation warning in the wrong order. + + 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 + extended summary. + """ + def method_wo_docstrings(self): pass @@ -772,6 +784,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 ecb02071c5bb6..2baac5f2c7e31 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', @@ -492,12 +493,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,6 +628,10 @@ def get_validation_data(doc): errs.append(error('GL07', correct_sections=', '.join(correct_order))) + if (doc.deprecated_with_directive + and not doc.extended_summary.startswith('.. deprecated:: ')): + errs.append(error('GL09')) + if not doc.summary: errs.append(error('SS01')) else: