Skip to content

DOC: Validate in docstrings that numpy and pandas are not imported #23161

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 13 commits into from
Nov 4, 2018
Merged

DOC: Validate in docstrings that numpy and pandas are not imported #23161

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
8655fdd
Check numpy and pandas in Examples
thoo Oct 15, 2018
5c071ec
Made changes as recommended
thoo Oct 16, 2018
5aff727
remove rstrip
thoo Oct 16, 2018
374c9ea
remove BadExamples class
thoo Oct 27, 2018
881b011
Merge remote-tracking branch 'repo_org/master' into check_np_pd_fromE…
thoo Oct 27, 2018
d824414
Merge remote-tracking branch 'repo_org/master' into check_np_pd_fromE…
thoo Oct 27, 2018
5d785c3
Merge remote-tracking branch 'repo_org/master' into check_np_pd_fromE…
thoo Nov 3, 2018
3e512ac
Change as recommended
thoo Nov 3, 2018
a2011b2
Change double to single quote
thoo Nov 3, 2018
0243b91
a few more changes
thoo Nov 3, 2018
d123b5c
a few more changes
thoo Nov 3, 2018
ec78655
changes in return
thoo Nov 3, 2018
ce37c8a
Retrigger Travis CI
thoo Nov 4, 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
20 changes: 19 additions & 1 deletion scripts/tests/test_validate_docstrings.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -502,6 +502,20 @@ def no_punctuation(self):
return "Hello world!"


class BadExamples(object):
Copy link
Member

Choose a reason for hiding this comment

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

I believe there is already an example that imports both of these:

pandas/scripts/tests/test_validate_docstrings.py

Line 334 in 5aff727

>>> import numpy as np

Any reason we don't leverage that instead of creating a new class?


def npPd_import(self):
Copy link
Member

Choose a reason for hiding this comment

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

this name is a bit cryptic, can you use something more clear.

"""
Provide example with numpy and pandas import
Copy link
Member

Choose a reason for hiding this comment

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

Can you finish this with a period, so it doesn't generate an error for it.


Examples
--------
import numpy as np
import pandas as pd
Copy link
Member

Choose a reason for hiding this comment

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

The code in examples start by >>>

It'd be good to have tests for import numpy and import pandas (without the aliases), and have each of them separate. And also a case when something else is imported (e.g. import datetime)

Not sure if in the good docstrings in the tests we have examples somewhere. We should, to make sure the error is not reported when import numpy... is not present.

"""
pass


class TestValidator(object):

def _import_path(self, klass=None, func=None):
Expand Down Expand Up @@ -600,7 +614,11 @@ def test_bad_generic_functions(self, func):
pytest.param('BadReturns', 'no_description', ('foo',),
marks=pytest.mark.xfail),
pytest.param('BadReturns', 'no_punctuation', ('foo',),
marks=pytest.mark.xfail)
marks=pytest.mark.xfail),
# Examples
('BadExamples', 'npPd_import',
('Examples should not have `import pandas as pd` ',
'Examples should not have `import numpy as np` ',))
])
def test_bad_examples(self, capsys, klass, func, msgs):
result = validate_one(self._import_path(klass=klass, func=func)) # noqa:F821
Expand Down
6 changes: 6 additions & 0 deletions scripts/validate_docstrings.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -512,6 +512,12 @@ def validate_one(func_name):
examples_errs = doc.examples_errors
if examples_errs:
errs.append('Examples do not pass tests')
if 'import numpy as np' in ' '.join(doc.examples):
Copy link
Member

Choose a reason for hiding this comment

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

I think it'd be good to use the module doctest to extract the content of the code in the examples. Meaning that something like this:

Examples
--------
This example does not import pandas as pd
>>> pd.Series(['pd is assumed to be imported as we want'])

should not generate an error.

And probably you want to include an example like this in the tests.

errs.append(' Examples should not have '
'`import numpy as np` ')
if 'import pandas as pd' in ' '.join(doc.examples):
errs.append(' Examples should not have '
'`import pandas as pd` ')

return {'type': doc.type,
'docstring': doc.clean_doc,
Expand Down