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'] )