Skip to content

DOC: Add ignore-deprecate argument to validate_docstrings.py #23650

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 25 commits into from
Nov 18, 2018
Merged

DOC: Add ignore-deprecate argument to validate_docstrings.py #23650

Show file tree
Hide file tree
Changes from 23 commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
e1fc4d5
add ignore-deprecate argument and add pytest
charlesdong1991 Nov 12, 2018
a08cb6d
fix flake8
charlesdong1991 Nov 12, 2018
42e372f
correct argument name
charlesdong1991 Nov 12, 2018
e569cf2
code changed based on review
charlesdong1991 Nov 12, 2018
09be5aa
change name and help description
charlesdong1991 Nov 12, 2018
e7a723b
add ignore_deprecated description for functiondocstring
charlesdong1991 Nov 12, 2018
70b0fcb
debug the error
charlesdong1991 Nov 13, 2018
66b9de3
debug the error
charlesdong1991 Nov 13, 2018
f5d28fe
set default value for ignore-deprecated
charlesdong1991 Nov 13, 2018
49188dd
bug fixing
charlesdong1991 Nov 13, 2018
901b943
add positional argument for lambda
charlesdong1991 Nov 13, 2018
c1f44a4
remove wrong lambda
charlesdong1991 Nov 13, 2018
1095a9a
add argument for setattr
charlesdong1991 Nov 13, 2018
26e1d04
correct argument name
charlesdong1991 Nov 13, 2018
b199099
assign true to ignore deprecated
charlesdong1991 Nov 13, 2018
b384e79
debug the error
charlesdong1991 Nov 13, 2018
a0f9d21
correct the assert value
charlesdong1991 Nov 13, 2018
af35c19
modify pytest
charlesdong1991 Nov 13, 2018
f1a66a6
rewrite pytest
charlesdong1991 Nov 13, 2018
79e5706
remove added part to test if the failure caused by my code
charlesdong1991 Nov 14, 2018
83cc28c
put tests back
charlesdong1991 Nov 15, 2018
1ed082a
remove curly bracket position
charlesdong1991 Nov 15, 2018
14e522a
change formatting
charlesdong1991 Nov 15, 2018
2418c0c
remove redunctant default value
charlesdong1991 Nov 15, 2018
f20fee1
set default to False
charlesdong1991 Nov 15, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 34 additions & 10 deletions scripts/tests/test_validate_docstrings.py
View file
Open in desktop
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=None: {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry I didn't see that before... ignore_deprecated expects a boolean value, I don't think we should pass None. And I see that it has a default value of False that is what we want. So, can you restore the original code? I think it should work, right?

Copy link
Member Author

@charlesdong1991 charlesdong1991 Nov 15, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ahh, i did this because i thought right now, validate_all takes in two arguments, and although ignore_deprecated has beed set to False by default, when we use lambda to create this mock data, we still need to assign a variable as a kind of placeholder, otherwise, there will be an error raised... can I still keep this, and remove None so that it looks like lambda: prefix, ignore_deprecated , please share your thoughts! And thanks for the quick response! @datapythonista

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

oh, that's right, I checked it fast and didn't see those are the arguments of the mock function, not the parameters being passed. In that case set ignore_deprecated=False, so we have the same signature in the mock as in the mocked function.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

oh, yeah, changed to False! thx for the feedback!

'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=None: {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same here, and in the rest of cases

'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=None: {
'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=None: {
'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
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -722,7 +722,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 @@ -732,6 +732,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 @@ -750,6 +752,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 @@ -771,13 +775,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 @@ -791,7 +797,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 @@ -882,8 +888,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))