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