Skip to content

Commit

Permalink
DOC: Add ignore-deprecate argument to validate_docstrings.py (#23650)
Browse files Browse the repository at this point in the history
  • Loading branch information
@charlesdong1991 @jorisvandenbossche
charlesdong1991 authored and jorisvandenbossche committed Nov 18, 2018
1 parent 24bce1a commit 1250500
Show file tree
Hide file tree
Showing 2 changed files with 49 additions and 14 deletions.
44 changes: 34 additions & 10 deletions scripts/tests/test_validate_docstrings.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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')],
Expand All @@ -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')]},
Expand All @@ -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')],
Expand All @@ -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
19 changes: 15 additions & 4 deletions scripts/validate_docstrings.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
-------
Expand All @@ -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']
Expand All @@ -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
Expand All @@ -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)
Expand Down Expand Up @@ -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))

0 comments on commit 1250500

Please sign in to comment.