def test_extract_docstring_info_check_error(self):
## Test for incorrectly formmatted docstring raising error
summary4 = """
Description of docstring which should fail.
:returns:param:
"""
with self.assertRaises(ValueError):
_extract_docstring_info({}, summary4, "error string")
summary5 = """
Description of malformed docstring.
Raises:
Error that should fail: if condition `x`.
"""
with self.assertRaises(KeyError):
_extract_docstring_info({}, summary5, "malformed docstring")
def test_extract_docstring_info_with_xref(self):
## Test with xref included in the summary, ensure they're processed as-is
summary_info_want = {
'variables': {
'arg1': {
'var_type':
'<xref uid="google.spanner_v1.type.Type">Type</xref>',
'description': 'simple description.'
},
'arg2': {
'var_type': '~google.spanner_v1.type.dict',
'description': 'simple description for `arg2`.'
}
},
'returns': [{
'var_type': '<xref uid="Pair">Pair</xref>',
'description': 'simple description for return value.'
}],
'exceptions': [{
'var_type':
'<xref uid="SpannerException">SpannerException</xref>',
'description': 'if `condition x`.'
}]
}
summary = """
Simple test for docstring.
:type arg1: <xref uid="google.spanner_v1.type.Type">Type</xref>
:param arg1: simple description.
:param arg2: simple description for `arg2`.
:type arg2: ~google.spanner_v1.type.dict
:rtype: <xref uid="Pair">Pair</xref>
:returns: simple description for return value.
:raises <xref uid="SpannerException">SpannerException</xref>: if `condition x`.
"""
summary_info_got = {'variables': {}, 'returns': [], 'exceptions': []}
top_summary_got = _extract_docstring_info(summary_info_got, summary,
"")
self.maxDiff = None
# Same as the top summary from previous example, compare with that
self.assertEqual(top_summary_got, self.top_summary1_want)
self.assertDictEqual(summary_info_got, summary_info_want)
def test_extract_docstring_info_check_parser(self):
## Test for parser to correctly scan docstring tokens and not custom fields
summary_info3_want = {'variables': {}, 'returns': [], 'exceptions': []}
summary3 = """
Union[int, None]: Expiration time in milliseconds for a partition.
If :attr:`partition_expiration` is set and <xref:type_> is
not set, :attr:`type_` will default to
:attr:`~google.cloud.bigquery.table.TimePartitioningType.DAY`.
It could return :param: with :returns as well.
"""
summary_info3_got = {'variables': {}, 'returns': [], 'exceptions': []}
# Nothing should change
top_summary3_want = summary3
top_summary3_got = _extract_docstring_info(summary_info3_got, summary3,
"")
self.assertEqual(top_summary3_got, top_summary3_want)
self.assertEqual(summary_info3_got, summary_info3_want)
def test_extract_docstring_info_mixed_format(self):
## Test for input coming in mixed format.
summary2 = """
Simple test for docstring.
:type arg1: int
:param arg1: simple description.
:param arg2: simple description for `arg2`.
:type arg2: str
:rtype: str
:returns: simple description for return value.
:raises AttributeError: if `condition x`.
"""
summary_info2_got = {'variables': {}, 'returns': [], 'exceptions': []}
top_summary2_got = _extract_docstring_info(summary_info2_got, summary2,
"")
# Output should be same as test 1 with normal input.
self.assertEqual(top_summary2_got, self.top_summary1_want)
self.assertEqual(summary_info2_got, self.summary_info1_want)
def test_extract_docstring_info_normal_input(self):
## Test for normal input
summary_info1_got = {'variables': {}, 'returns': [], 'exceptions': []}
summary1 = """
Simple test for docstring.
Args:
arg1(int): simple description.
arg2(str): simple description for `arg2`.
Returns:
str: simple description for return value.
Raises:
AttributeError: if `condition x`.
"""
top_summary1_got = _extract_docstring_info(summary_info1_got, summary1,
"")
self.assertEqual(top_summary1_got, self.top_summary1_want)
self.assertEqual(summary_info1_got, self.summary_info1_want)