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 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_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_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_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 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 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 _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_has_everything_for_sphinx_multiline(self):
has_everything_multiline_root = '\n'.join([
'Short decscription.', '', 'Long description.', '',
':param Test: Some value.', ' Over multiples lines.',
':raises IntegrityError: Sometimes.',
' Also over multiples lines', ':yields: The occasional value.',
':returns: When it completes.',
' But what about multiple lines?', ''
])
docstring = Docstring.from_sphinx(has_everything_multiline_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, ))
