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))