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_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 setUpClass(cls, *args, **kwargs):
super().setUpClass(*args, **kwargs)
cls.equivalent_docstrings = list()
for google_doc, sphinx_doc, numpy_doc in cls._equivalent_docstrings:
cls.equivalent_docstrings.append((
Docstring.from_google(google_doc),
Docstring.from_sphinx(sphinx_doc),
Docstring.from_numpy(numpy_doc),
))
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 parse_golden(self, golden):
if golden['type'] == 'GOOGLE':
docstring = Docstring.from_google(golden['docstring'])
elif golden['type'] == 'SPHINX':
docstring = Docstring.from_sphinx(golden['docstring'])
elif golden['type'] == 'NUMPY':
docstring = Docstring.from_numpy(golden['docstring'])
else:
raise Exception('Unsupported docstring type {}'.format(
golden['type']
))
return docstring, golden['metadata']
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'],
)
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'])
elif golden['type'] == 'NUMPY':
assert isinstance(golden['docstring'], str)
docstring = Docstring.from_numpy(golden['docstring'])
else:
raise Exception('Unsupported docstring type {}'.format(
golden['type']))
return docstring
def test_satisfies_strictness_full_description(self):
parameters = [
(None, False),
('', False),
('Dostring with just title.', False),
(
'\n'.join([
'Dostring with title, long description and parameters.',
'',
'Long description goes here.',
'',
'Parameters',
'----------',
'x: int',
' The only parameter.',
'',
'Returns',
'-------',
'int',
' Magic, random number.',
'',
]),
False,
),
(
'\n'.join([
'Dostring with only long,',
'long, really long description.',
'',
]),
False,
),
]
for raw_docstring, is_strictness_satisfied in parameters:
docstring = Docstring.from_numpy(raw_docstring)
with self.subTest(raw_docstring):
self.assertIs(
docstring.satisfies_strictness(
Strictness.FULL_DESCRIPTION, ),
is_strictness_satisfied,
msg=raw_docstring,
)
def test_satisfies_strictness_short_description(self):
parameters = [
(None, False),
('', False),
('Dostring with just title.', True),
(
'\n'.join([
'Dostring with title and parameters.',
'',
'Parameters',
'----------',
'x: int',
' The first parameter.',
'',
'y: Optional[int]',
' The second parameter.',
'',
]),
False,
),
(
'\n'.join([
'Dostring with only long,',
'long, really long description.',
'',
]),
False,
),
]
for raw_docstring, is_strictness_satisfied in parameters:
docstring = Docstring.from_numpy(raw_docstring)
with self.subTest(raw_docstring):
self.assertIs(
docstring.satisfies_strictness(
Strictness.SHORT_DESCRIPTION, ),
is_strictness_satisfied,
msg=raw_docstring,
)
def test_arguments_section_with_break_after_description(self):
raw_docstring = '\n'.join([
'Has arguments.',
'',
'Parameters',
'----------',
'x: int',
' The first parameter.',
'',
'y: Optional[int]',
' The second parameter.',
' ',
'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'],
)
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),
])
numpy_params = [
'{} : {}\n An explanation'.format(name, _type)
for name, _type in zip(names, types)
]
numpy_docstring = '\n'.join([
short_description, '', 'Parameters', '----------',
'\n'.join(numpy_params)
])
google_doc = Docstring.from_google(google_docstring)
sphinx_doc = Docstring.from_sphinx(sphinx_docstring)
numpy_doc = Docstring.from_numpy(numpy_docstring)
items = google_doc.get_items(Sections.ARGUMENTS_SECTION)
self.assertTrue(items == sorted(items), 'The items should be sorted.')
google_items = google_doc.get_items(Sections.ARGUMENTS_SECTION)
self.assertEqual(
google_items,
sphinx_doc.get_items(Sections.ARGUMENTS_SECTION),
'Google and Sphinx items should be the same.',
)
self.assertEqual(google_items,
numpy_doc.get_items(Sections.ARGUMENTS_SECTION))
google_args_section = google_doc.get_types(Sections.ARGUMENTS_SECTION)
self.assertEqual(
google_args_section,
sphinx_doc.get_types(Sections.ARGUMENTS_SECTION),
'Google and Sphinx types should be the same.',
)
self.assertEqual(
google_args_section,
numpy_doc.get_types(Sections.ARGUMENTS_SECTION),
)
