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), )