def test_has_everything_for_sphinx(self):
has_everything_root = '\n'.join([
'Short decscription.', '', 'Long description.', '',
':param x: Some value.', ':raises IntegrityError: Sometimes.',
':yields: The occasional value.', ':returns: When it completes.',
''
])
docstring = Docstring.from_sphinx(has_everything_root)
for section in [
Sections.SHORT_DESCRIPTION,
Sections.LONG_DESCRIPTION,
Sections.ARGUMENTS_SECTION,
Sections.RAISES_SECTION,
Sections.YIELDS_SECTION,
Sections.RETURNS_SECTION,
]:
self.assertTrue(
docstring.get_section(section),
'Expected to have section {}, but it did not.'.format(
section, ))
has_only_short_description = '\n'.join(['Short description'])
docstring = Docstring.from_google(has_only_short_description)
self.assertTrue(docstring.get_section(Sections.SHORT_DESCRIPTION), )
self.assertFalse(
any([
docstring.get_section(Sections.LONG_DESCRIPTION),
docstring.get_section(Sections.ARGUMENTS_SECTION),
docstring.get_section(Sections.RAISES_SECTION),
docstring.get_section(Sections.YIELDS_SECTION),
docstring.get_section(Sections.RETURNS_SECTION),
]))
def test_has_everything_for_sphinx(self):
has_everything_root = sphinx.parse(Peaker(lex('\n'.join([
'Short decscription.',
'',
'Long description.',
'',
':param x: Some value.',
':raises IntegrityError: Sometimes.',
':yields: The occasional value.',
':returns: When it completes.',
''
])), lookahead=3))
docstring = Docstring.from_sphinx(has_everything_root)
self.assertTrue(all([
docstring.has_short_description(),
docstring.has_long_description(),
docstring.has_args_section(),
docstring.has_raises_section(),
docstring.has_yields_section(),
docstring.has_returns_section(),
]))
has_only_short_description = parse(Peaker(lex('\n'.join([
'Short description'
])), lookahead=3))
docstring = Docstring.from_google(has_only_short_description)
self.assertTrue(
docstring.has_short_description(),
)
self.assertFalse(any([
docstring.has_long_description(),
docstring.has_args_section(),
docstring.has_raises_section(),
docstring.has_yields_section(),
docstring.has_returns_section(),
]))
def test_has_everything_for_sphinx(self):
has_everything_root = sphinx.parse(
Peaker(lex('\n'.join([
'Short decscription.', '', 'Long description.', '',
':param x: Some value.', ':raises IntegrityError: Sometimes.',
':yields: The occasional value.',
':returns: When it completes.', ''
])),
lookahead=3))
docstring = Docstring.from_sphinx(has_everything_root)
self.assertTrue(
all([
docstring.get_section(Sections.SHORT_DESCRIPTION),
docstring.get_section(Sections.LONG_DESCRIPTION),
docstring.get_section(Sections.ARGUMENTS_SECTION),
docstring.get_section(Sections.RAISES_SECTION),
docstring.get_section(Sections.YIELDS_SECTION),
docstring.get_section(Sections.RETURNS_SECTION),
]))
has_only_short_description = google.parse(
Peaker(lex('\n'.join(['Short description'])), lookahead=3))
docstring = Docstring.from_google(has_only_short_description)
self.assertTrue(docstring.get_section(Sections.SHORT_DESCRIPTION), )
self.assertFalse(
any([
docstring.get_section(Sections.LONG_DESCRIPTION),
docstring.get_section(Sections.ARGUMENTS_SECTION),
docstring.get_section(Sections.RAISES_SECTION),
docstring.get_section(Sections.YIELDS_SECTION),
docstring.get_section(Sections.RETURNS_SECTION),
]))
def setUpClass(cls, *args, **kwargs):
super().setUpClass(*args, **kwargs)
cls.equivalent_docstrings = list()
for google_doc, sphinx_doc in cls._equivalent_docstrings:
cls.equivalent_docstrings.append((
Docstring.from_google(google_doc),
Docstring.from_sphinx(sphinx_doc),
))
def parse_golden(self, golden):
if golden['type'] == 'GOOGLE':
docstring = Docstring.from_google(golden['docstring'])
elif golden['type'] == 'SPHINX':
docstring = Docstring.from_sphinx(golden['docstring'])
else:
raise Exception('Unsupported docstring type {}'.format(
golden['type']))
return docstring, golden['metadata']
def setUpClass(cls, *args, **kwargs):
super().setUpClass(*args, **kwargs)
cls.equivalent_docstrings = list()
for google_doc, sphinx_doc in cls._equivalent_docstrings:
google_root = google.parse(Peaker(lex(google_doc), 3))
sphinx_root = sphinx.parse(Peaker(lex(sphinx_doc), 2))
cls.equivalent_docstrings.append((
Docstring.from_google(google_root),
Docstring.from_sphinx(sphinx_root),
))
def _parse_golden(self, golden):
# type: (Golden) -> BaseDocstring
if golden['type'] == 'GOOGLE':
assert isinstance(golden['docstring'], str)
docstring = Docstring.from_google(golden['docstring'])
elif golden['type'] == 'SPHINX':
assert isinstance(golden['docstring'], str)
docstring = Docstring.from_sphinx(golden['docstring'])
else:
raise Exception('Unsupported docstring type {}'.format(
golden['type']))
return docstring
def test_type_and_name_always_associated(self):
"""Make sure the type goes to the correct name."""
names = ['x', 'y', 'a', 'z', 'q']
types = ['int', 'float', 'Decimal', 'str', 'Any']
short_description = 'A short docstring.'
# Change the types of the parameters.
shuffle(names)
shuffle(types)
sphinx_params = [
':param {}: An explanation'.format(name) for name in names
] + [
':type {}: {}'.format(name, _type)
for name, _type in zip(names, types)
]
shuffle(sphinx_params)
sphinx_docstring = '\n'.join(
[short_description, '', '\n'.join(sphinx_params)])
google_params = [
' {} ({}): An explanation.'.format(name, _type)
for name, _type in zip(names, types)
]
google_docstring = '\n'.join([
short_description,
'',
'Args:',
'\n'.join(google_params),
])
google_doc = Docstring.from_google(
google.parse(Peaker(lex(google_docstring), 3)))
sphinx_doc = Docstring.from_sphinx(
sphinx.parse(Peaker(lex(sphinx_docstring), 2)))
items = google_doc.get_items(Sections.ARGUMENTS_SECTION)
self.assertTrue(items == sorted(items), 'The items should be sorted.')
self.assertEqual(
google_doc.get_items(Sections.ARGUMENTS_SECTION),
sphinx_doc.get_items(Sections.ARGUMENTS_SECTION),
'Google and Sphinx items should be the same.',
)
self.assertEqual(
google_doc.get_types(Sections.ARGUMENTS_SECTION),
sphinx_doc.get_types(Sections.ARGUMENTS_SECTION),
'Google and Sphinx types should be the same.',
)
def test_multiple_arguments_on_one_line(self):
"""Make sure we can extract from multiple args on one line."""
# By forcing the individual elements to be sorted, we
# force an overall sorting. (The docstring will be sorting
# by the first element in a combined argument. Once split,
# the individual arguments will not necessarily be in order.)
# This forces them to be.
args = sorted(self._get_args())
types = self._get_types(args)
sorted_args = sorted(args)
sorted_types = [_type for arg, _type in sorted(zip(args, types))]
argtypes = self._get_argtype_pairs(args, types)
for combo in self._combine(argtypes):
raw_docstring = self.generate_docstring(combo)
docstring = Docstring.from_numpy(raw_docstring)
items = docstring.get_items(Sections.ARGUMENTS_SECTION)
types = docstring.get_types(Sections.ARGUMENTS_SECTION)
self.assertEqual(
items,
sorted_args,
)
self.assertEqual(
types,
sorted_types,
)
def test_get_argument_types(self):
"""Make sure we can get a dictionary of arguments to types."""
root = sphinx.parse(
Peaker(lex('\n'.join([
'Something.',
'',
':param x: The first.',
':param y: The second.',
':type x: int',
':type y: List[int], optional'
'\n',
])),
lookahead=3))
from darglint.utils import generate_dot
with open('_data/example.dot', 'w') as fout:
fout.write(generate_dot(root))
docstring = Docstring.from_sphinx(root)
argtypes = dict(
zip(
docstring.get_items(Sections.ARGUMENTS_SECTION) or [],
docstring.get_types(Sections.ARGUMENTS_SECTION) or [],
))
self.assertEqual(
argtypes['x'],
'int',
)
self.assertEqual(
argtypes['y'],
'List[int], optional',
)
def test_get_argument_types(self):
"""Make sure we can get a dictionary of arguments to types."""
root = sphinx.parse(
Peaker(lex('\n'.join([
'Something.',
'',
':param x: The first.',
':param y: The second.',
':type x: int',
':type y: List[int], optional'
'\n',
])),
lookahead=3))
docstring = Docstring.from_sphinx(root)
argtypes = dict(
zip(
docstring.get_items(Sections.ARGUMENTS_SECTION) or [],
docstring.get_types(Sections.ARGUMENTS_SECTION) or [],
))
self.assertEqual(
argtypes['x'],
'int',
)
self.assertEqual(
argtypes['y'],
'List[int], optional',
)
def test_get_short_description(self):
"""Ensure we can get the short description."""
root = google.parse(
Peaker(lex('Nothing but a short description.'), lookahead=3))
docstring = Docstring.from_google(root)
self.assertEqual(docstring.get_section(Sections.SHORT_DESCRIPTION),
'Nothing but a short description.')
def test_arguments_section_with_breaks_in_lines_and_indents(self):
raw_docstring = '\n'.join([
'Has arguments.',
'',
'Parameters',
'----------',
'x: int',
' The first parameter.',
' ',
' Can be the only parameter.',
'y: Optional[int]',
' The second parameter.',
'',
' Can also be added.',
'z: Optional[int]',
' The third parameter.',
'',
])
docstring = Docstring.from_numpy(raw_docstring)
self.assertTrue(
docstring.get_section(Sections.ARGUMENTS_SECTION) is not None)
self.assertEqual(
docstring.get_items(Sections.ARGUMENTS_SECTION),
['x', 'y', 'z'],
)
self.assertEqual(
docstring.get_types(Sections.ARGUMENTS_SECTION),
['int', 'Optional[int]', 'Optional[int]'],
)
def test_get_short_description(self):
"""Ensure we can get the short description."""
root = parse(
Peaker(lex('Nothing but a short description.'), lookahead=3))
docstring = Docstring.from_google(root)
self.assertEqual(
docstring.short_description,
'Nothing but a short description.'
)
def test_global_noqa_star_body(self):
"""Ensure noqa with * means ignore everything."""
root = '\n'.join([
'A short explanation.',
'',
' # noqa: *',
'\n',
])
docstring = Docstring.from_google(root)
self.assertTrue(docstring.ignore_all)
def test_global_noqa_no_body(self):
"""Ensure an empty noqa body means ignore everything."""
root = parse(Peaker(lex('\n'.join([
'A short explanation.',
'',
' # noqa',
'\n',
])), lookahead=3))
docstring = Docstring.from_google(root)
self.assertTrue(docstring.ignore_all)
def test_has_section(self):
"""Make sure the docstring can tell if it has the given sections."""
has_everything_root = google.parse(
Peaker(lex('\n'.join([
'Short decscription.',
'',
'Long description.',
'',
'Args:',
' x: Some value.',
'',
'Raises:',
' IntegrityError: Sometimes.',
'',
'Yields:',
' The occasional value.',
'',
'Returns:',
' When it completes.',
])),
lookahead=3))
docstring = Docstring.from_google(has_everything_root)
self.assertTrue(
all([
docstring.get_section(Sections.SHORT_DESCRIPTION),
docstring.get_section(Sections.LONG_DESCRIPTION),
docstring.get_section(Sections.ARGUMENTS_SECTION),
docstring.get_section(Sections.RAISES_SECTION),
docstring.get_section(Sections.YIELDS_SECTION),
docstring.get_section(Sections.RETURNS_SECTION),
]))
has_only_short_description = google.parse(
Peaker(lex('\n'.join(['Short description'])), lookahead=3))
docstring = Docstring.from_google(has_only_short_description)
self.assertTrue(docstring.get_section(Sections.SHORT_DESCRIPTION), )
self.assertFalse(
any([
docstring.get_section(Sections.LONG_DESCRIPTION),
docstring.get_section(Sections.ARGUMENTS_SECTION),
docstring.get_section(Sections.RAISES_SECTION),
docstring.get_section(Sections.YIELDS_SECTION),
docstring.get_section(Sections.RETURNS_SECTION),
]))
def test_has_section(self):
"""Make sure the docstring can tell if it has the given sections."""
has_everything_root = parse(Peaker(lex('\n'.join([
'Short decscription.',
'',
'Long description.',
'',
'Args:',
' x: Some value.',
'',
'Raises:',
' IntegrityError: Sometimes.',
'',
'Yields:',
' The occasional value.',
'',
'Returns:',
' When it completes.',
])), lookahead=3))
docstring = Docstring.from_google(has_everything_root)
self.assertTrue(all([
docstring.has_short_description(),
docstring.has_long_description(),
docstring.has_args_section(),
docstring.has_raises_section(),
docstring.has_yields_section(),
docstring.has_returns_section(),
]))
has_only_short_description = parse(Peaker(lex('\n'.join([
'Short description'
])), lookahead=3))
docstring = Docstring.from_google(has_only_short_description)
self.assertTrue(
docstring.has_short_description(),
)
self.assertFalse(any([
docstring.has_long_description(),
docstring.has_args_section(),
docstring.has_raises_section(),
docstring.has_yields_section(),
docstring.has_returns_section(),
]))
def test_get_long_description(self):
"""Make sure we can get the long description."""
root = '\n'.join([
'Ignore short.',
'',
'Long description should be contiguous.',
'',
])
docstring = Docstring.from_google(root)
self.assertEqual(docstring.get_section(Sections.LONG_DESCRIPTION),
'Long description should be contiguous.')
def test_extract_simplest_raises_section(self):
raw_docstring = '\n'.join([
'Raises an error.',
'',
'Raises',
'------',
'AssertionError'
'',
])
docstring = Docstring.from_numpy(raw_docstring)
self.assertTrue(
docstring.get_section(Sections.RAISES_SECTION) is not None)
def test_arguments_section_with_newline(self):
"""Make sure we can parse an arguments section with a newline."""
root = '\n'.join([
'Something.',
'',
':param condition:',
' The first.',
'\n',
])
docstring = Docstring.from_sphinx(root)
items = docstring.get_items(Sections.ARGUMENTS_SECTION)
self.assertEqual(items, ['condition'])
def test_get_arguments_description(self):
"""Make sure we can get the arguments description."""
root = '\n'.join([
'Something.',
'',
'Args:',
' x: An integer.',
'\n',
])
docstring = Docstring.from_google(root)
section = docstring.get_section(Sections.ARGUMENTS_SECTION)
self.assertEqual(section, 'Args:\n x: An integer.')
def test_get_exception_types(self):
"""Make sure we can get the types of exceptions raised."""
root = '\n'.join([
'Problematic.',
'',
'Raises:',
' IndexError: Frequently.',
' DoesNotExist: Always.',
'\n',
])
docstring = Docstring.from_google(root)
self.assertEqual(docstring.get_items(Sections.RAISES_SECTION),
sorted(['IndexError', 'DoesNotExist']))
def test_get_raises_description(self):
"""Make sure we can get the raises description."""
root = '\n'.join([
'Check if there\'s a problem.',
'',
'Raises:',
' ProblemException: if there is a problem.',
'\n',
])
docstring = Docstring.from_google(root)
self.assertEqual(
docstring.get_section(Sections.RAISES_SECTION),
'Raises:\n ProblemException: if there is a problem.')
def test_get_long_description(self):
"""Make sure we can get the long description."""
root = parse(Peaker(lex('\n'.join([
'Ignore short.',
'',
'Long description should be contiguous.',
'',
])), lookahead=3))
docstring = Docstring.from_google(root)
self.assertEqual(
docstring.long_description,
'Long description should be contiguous.\n'
)
def test_get_yields_description(self):
"""Make sure we can get the yields description."""
root = '\n'.join([
'To pedestrians.',
'',
'Yields:',
' To pedestrians.',
'\n',
])
docstring = Docstring.from_google(root)
self.assertEqual(
docstring.get_section(Sections.YIELDS_SECTION),
'Yields:\n To pedestrians.',
)
def test_get_yields_type(self):
"""Make sure we can get the yields type."""
root = '\n'.join([
'Get slavic cats.',
'',
'Yields:',
' Cat: The slavic ones.',
'\n',
])
docstring = Docstring.from_google(root)
self.assertEqual(
docstring.get_types(Sections.YIELDS_SECTION),
'Cat',
)
def test_get_arguments_description(self):
"""Make sure we can get the arguments description."""
root = google.parse(
Peaker(lex('\n'.join([
'Something.',
'',
'Args:',
' x: An integer.',
'\n',
])),
lookahead=3))
docstring = Docstring.from_google(root)
self.assertEqual(docstring.get_section(Sections.ARGUMENTS_SECTION),
'Args:\n x: An integer.')
def test_get_return_type(self):
"""Make sure we can get the return type described."""
root = '\n'.join([
'Ferment potato.',
'',
'Returns:',
' Alcohol: Vodka.',
'\n',
])
docstring = Docstring.from_google(root)
self.assertEqual(
docstring.get_types(Sections.RETURNS_SECTION),
'Alcohol',
)
def test_arguments_without_description(self):
raw_docstring = '\n'.join([
'Has arguments.',
'',
'Parameters',
'----------',
'x',
'',
])
docstring = Docstring.from_numpy(raw_docstring)
self.assertEqual(
docstring.get_items(Sections.ARGUMENTS_SECTION),
['x'],
)
