DOC: Add ignore-deprecate argument to validate_docstrings.py (pandas-dev#23650)

Author: charlesdong1991

scripts/tests/test_validate_docstrings.py

@@ -817,6 +817,20 @@ def test_bad_examples(self, capsys, klass, func, msgs):
         for msg in msgs:
             assert msg in ' '.join(err[1] for err in result['errors'])
 
+    def test_validate_all_ignore_deprecated(self, monkeypatch):
+        monkeypatch.setattr(
+            validate_docstrings, 'validate_one', lambda func_name: {
+                'docstring': 'docstring1',
+                'errors': [('ER01', 'err desc'),
+                           ('ER02', 'err desc'),
+                           ('ER03', 'err desc')],
+                'warnings': [],
+                'examples_errors': '',
+                'deprecated': True})
+        result = validate_docstrings.validate_all(prefix=None,
+                                                  ignore_deprecated=True)
+        assert len(result) == 0
+
 
 class TestApiItems(object):
     @property
@@ -907,12 +921,14 @@ def test_exit_status_for_validate_one(self, monkeypatch):
         exit_status = validate_docstrings.main(func_name='docstring1',
                                                prefix=None,
                                                errors=[],
-                                               output_format='default')
+                                               output_format='default',
+                                               ignore_deprecated=False)
         assert exit_status == 0
 
     def test_exit_status_errors_for_validate_all(self, monkeypatch):
         monkeypatch.setattr(
-            validate_docstrings, 'validate_all', lambda prefix: {
+            validate_docstrings, 'validate_all',
+            lambda prefix, ignore_deprecated=False: {
                 'docstring1': {'errors': [('ER01', 'err desc'),
                                           ('ER02', 'err desc'),
                                           ('ER03', 'err desc')],
@@ -925,25 +941,29 @@ def test_exit_status_errors_for_validate_all(self, monkeypatch):
         exit_status = validate_docstrings.main(func_name=None,
                                                prefix=None,
                                                errors=[],
-                                               output_format='default')
+                                               output_format='default',
+                                               ignore_deprecated=False)
         assert exit_status == 5
 
     def test_no_exit_status_noerrors_for_validate_all(self, monkeypatch):
         monkeypatch.setattr(
-            validate_docstrings, 'validate_all', lambda prefix: {
+            validate_docstrings, 'validate_all',
+            lambda prefix, ignore_deprecated=False: {
                 'docstring1': {'errors': [],
                                'warnings': [('WN01', 'warn desc')]},
                 'docstring2': {'errors': []}})
         exit_status = validate_docstrings.main(func_name=None,
                                                prefix=None,
                                                errors=[],
-                                               output_format='default')
+                                               output_format='default',
+                                               ignore_deprecated=False)
         assert exit_status == 0
 
     def test_exit_status_for_validate_all_json(self, monkeypatch):
         print('EXECUTED')
         monkeypatch.setattr(
-            validate_docstrings, 'validate_all', lambda prefix: {
+            validate_docstrings, 'validate_all',
+            lambda prefix, ignore_deprecated=False: {
                 'docstring1': {'errors': [('ER01', 'err desc'),
                                           ('ER02', 'err desc'),
                                           ('ER03', 'err desc')]},
@@ -952,12 +972,14 @@ def test_exit_status_for_validate_all_json(self, monkeypatch):
         exit_status = validate_docstrings.main(func_name=None,
                                                prefix=None,
                                                errors=[],
-                                               output_format='json')
+                                               output_format='json',
+                                               ignore_deprecated=False)
         assert exit_status == 0
 
     def test_errors_param_filters_errors(self, monkeypatch):
         monkeypatch.setattr(
-            validate_docstrings, 'validate_all', lambda prefix: {
+            validate_docstrings, 'validate_all',
+            lambda prefix, ignore_deprecated=False: {
                 'Series.foo': {'errors': [('ER01', 'err desc'),
                                           ('ER02', 'err desc'),
                                           ('ER03', 'err desc')],
@@ -973,11 +995,13 @@ def test_errors_param_filters_errors(self, monkeypatch):
         exit_status = validate_docstrings.main(func_name=None,
                                                prefix=None,
                                                errors=['ER01'],
-                                               output_format='default')
+                                               output_format='default',
+                                               ignore_deprecated=False)
         assert exit_status == 3
 
         exit_status = validate_docstrings.main(func_name=None,
                                                prefix=None,
                                                errors=['ER03'],
-                                               output_format='default')
+                                               output_format='default',
+                                               ignore_deprecated=False)
         assert exit_status == 1

scripts/validate_docstrings.py

@@ -716,7 +716,7 @@ def validate_one(func_name):
             'examples_errors': examples_errs}
 
 
-def validate_all(prefix):
+def validate_all(prefix, ignore_deprecated=False):
     """
     Execute the validation of all docstrings, and return a dict with the
     results.
@@ -726,6 +726,8 @@ def validate_all(prefix):
     prefix : str or None
         If provided, only the docstrings that start with this pattern will be
         validated. If None, all docstrings will be validated.
+    ignore_deprecated: bool, default False
+        If True, deprecated objects are ignored when validating docstrings.
 
     Returns
     -------
@@ -744,6 +746,8 @@ def validate_all(prefix):
         if prefix and not func_name.startswith(prefix):
             continue
         doc_info = validate_one(func_name)
+        if ignore_deprecated and doc_info['deprecated']:
+            continue
         result[func_name] = doc_info
 
         shared_code_key = doc_info['file'], doc_info['file_line']
@@ -765,13 +769,15 @@ def validate_all(prefix):
                 if prefix and not func_name.startswith(prefix):
                     continue
                 doc_info = validate_one(func_name)
+                if ignore_deprecated and doc_info['deprecated']:
+                    continue
                 result[func_name] = doc_info
                 result[func_name]['in_api'] = False
 
     return result
 
 
-def main(func_name, prefix, errors, output_format):
+def main(func_name, prefix, errors, output_format, ignore_deprecated):
     def header(title, width=80, char='#'):
         full_line = char * width
         side_len = (width - len(title) - 2) // 2
@@ -785,7 +791,7 @@ def header(title, width=80, char='#'):
 
     exit_status = 0
     if func_name is None:
-        result = validate_all(prefix)
+        result = validate_all(prefix, ignore_deprecated)
 
         if output_format == 'json':
             output = json.dumps(result)
@@ -876,8 +882,13 @@ def header(title, width=80, char='#'):
                            'list of error codes to validate. By default it '
                            'validates all errors (ignored when validating '
                            'a single docstring)')
+    argparser.add_argument('--ignore_deprecated', default=False,
+                           action='store_true', help='if this flag is set, '
+                           'deprecated objects are ignored when validating '
+                           'all docstrings')
 
     args = argparser.parse_args()
     sys.exit(main(args.function, args.prefix,
                   args.errors.split(',') if args.errors else None,
-                  args.format))
+                  args.format,
+                  args.ignore_deprecated))