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 = google.parse(
Peaker(lex('\n'.join([
'Something.',
'',
'Args:',
' x (int): The first.',
' y (List[int], optional): The second.',
'\n',
])),
lookahead=3))
docstring = Docstring.from_google(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 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_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 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 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 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 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_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_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 = 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_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 _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_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_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_yields_description(self):
"""Make sure we can get the yields description."""
root = parse(Peaker(lex('\n'.join([
'To pedestrians.',
'',
'Yields:',
' To pedestrians.',
'\n',
])), lookahead=3))
docstring = Docstring.from_google(root)
self.assertEqual(
docstring.yields_description,
'Yields:\n To pedestrians.\n',
)
def test_get_yields_type(self):
"""Make sure we can get the yields type."""
root = parse(Peaker(lex('\n'.join([
'Get slavic cats.',
'',
'Yields:',
' Cat: The slavic ones.',
'\n',
])), lookahead=3))
docstring = Docstring.from_google(root)
self.assertEqual(
docstring.get_yield_type(),
'Cat',
)
def test_get_raises_description(self):
"""Make sure we can get the raises description."""
root = parse(Peaker(lex('\n'.join([
'Check if there\'s a problem.',
'',
'Raises:',
' ProblemException: if there is a problem.',
'\n',
])), lookahead=3))
docstring = Docstring.from_google(root)
self.assertEqual(
docstring.raises_description,
'Raises:\n ProblemException: if there is a problem.\n'
)
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_section(self):
"""Make sure we can get the returns description."""
root = parse(Peaker(lex('\n'.join([
'Ferment corn.',
'',
'Returns:',
' Bourbon.',
'\n',
])), lookahead=3))
docstring = Docstring.from_google(root)
self.assertEqual(
docstring.returns_description,
'Returns:\n Bourbon.\n',
)
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_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_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_get_return_section(self):
"""Make sure we can get the returns description."""
root = '\n'.join([
'Ferment corn.',
'',
'Returns:',
' Bourbon.',
'\n',
])
docstring = Docstring.from_google(root)
self.assertEqual(
docstring.get_section(Sections.RETURNS_SECTION),
'Returns:\n Bourbon.',
)
def test_get_return_type(self):
"""Make sure we can get the return type described."""
root = parse(Peaker(lex('\n'.join([
'Ferment potato.',
'',
'Returns:',
' Alcohol: Vodka.',
'\n',
])), lookahead=3))
docstring = Docstring.from_google(root)
self.assertEqual(
docstring.get_return_type(),
'Alcohol',
)
def test_get_exception_types(self):
"""Make sure we can get the types of exceptions raised."""
root = parse(Peaker(lex('\n'.join([
'Problematic.',
'',
'Raises:',
' IndexError: Frequently.',
' DoesNotExist: Always.',
'\n',
])), lookahead=3))
docstring = Docstring.from_google(root)
self.assertEqual(
docstring.get_exception_types(),
['IndexError', 'DoesNotExist']
)
