def test_params() -> None:
docstring = parse("Short description")
assert len(docstring.params) == 0
docstring = parse("""
Short description
:param name: description 1
:param int priority: description 2
:param str? sender: description 3
:param str? message: description 4, defaults to 'hello'
""")
assert len(docstring.params) == 4
assert docstring.params[0].arg_name == "name"
assert docstring.params[0].type_name is None
assert docstring.params[0].description == "description 1"
assert docstring.params[0].default is None
assert not docstring.params[0].is_optional
assert docstring.params[1].arg_name == "priority"
assert docstring.params[1].type_name == "int"
assert docstring.params[1].description == "description 2"
assert not docstring.params[1].is_optional
assert docstring.params[1].default is None
assert docstring.params[2].arg_name == "sender"
assert docstring.params[2].type_name == "str"
assert docstring.params[2].description == "description 3"
assert docstring.params[2].is_optional
assert docstring.params[2].default is None
assert docstring.params[3].arg_name == "message"
assert docstring.params[3].type_name == "str"
assert (docstring.params[3].description ==
"description 4, defaults to 'hello'")
assert docstring.params[3].is_optional
assert docstring.params[3].default == "'hello'"
def test_yields() -> None:
"""Test parsing yields."""
docstring = parse("""
Short description
""")
assert docstring.returns is None
assert docstring.many_returns is not None
assert len(docstring.many_returns) == 0
docstring = parse("""
Short description
:yields: description
""")
assert docstring.returns is not None
assert docstring.returns.type_name is None
assert docstring.returns.description == "description"
assert docstring.returns.is_generator
assert docstring.many_returns is not None
assert len(docstring.many_returns) == 1
assert docstring.many_returns[0] == docstring.returns
docstring = parse("""
Short description
:yields int: description
""")
assert docstring.returns is not None
assert docstring.returns.type_name == "int"
assert docstring.returns.description == "description"
assert docstring.returns.is_generator
assert docstring.many_returns is not None
assert len(docstring.many_returns) == 1
assert docstring.many_returns[0] == docstring.returns
def test_params() -> None:
"""Test parsing params."""
docstring = parse("Short description")
assert len(docstring.params) == 0
docstring = parse("""
Short description
:param name: description 1
:param int priority: description 2
:param str? sender: description 3
:param str? message: description 4, defaults to 'hello'
:param str? multiline: long description 5,
defaults to 'bye'
""")
assert len(docstring.params) == 5
assert docstring.params[0].arg_name == "name"
assert docstring.params[0].type_name is None
assert docstring.params[0].description == "description 1"
assert docstring.params[0].default is None
assert not docstring.params[0].is_optional
assert docstring.params[1].arg_name == "priority"
assert docstring.params[1].type_name == "int"
assert docstring.params[1].description == "description 2"
assert not docstring.params[1].is_optional
assert docstring.params[1].default is None
assert docstring.params[2].arg_name == "sender"
assert docstring.params[2].type_name == "str"
assert docstring.params[2].description == "description 3"
assert docstring.params[2].is_optional
assert docstring.params[2].default is None
assert docstring.params[3].arg_name == "message"
assert docstring.params[3].type_name == "str"
assert (docstring.params[3].description ==
"description 4, defaults to 'hello'")
assert docstring.params[3].is_optional
assert docstring.params[3].default == "'hello'"
assert docstring.params[4].arg_name == "multiline"
assert docstring.params[4].type_name == "str"
assert (docstring.params[4].description ==
"long description 5,\ndefaults to 'bye'")
assert docstring.params[4].is_optional
assert docstring.params[4].default == "'bye'"
docstring = parse("""
Short description
:param a: description a
:type a: int
:param int b: description b
""")
assert len(docstring.params) == 2
assert docstring.params[0].arg_name == "a"
assert docstring.params[0].type_name == "int"
assert docstring.params[0].description == "description a"
assert docstring.params[0].default is None
assert not docstring.params[0].is_optional
def test_deprecation() -> None:
"""Test parsing deprecation notes."""
docstring = parse(":deprecation: 1.1.0 this function will be removed")
assert docstring.deprecation is not None
assert docstring.deprecation.version == "1.1.0"
assert docstring.deprecation.description == "this function will be removed"
docstring = parse(":deprecation: this function will be removed")
assert docstring.deprecation is not None
assert docstring.deprecation.version is None
assert docstring.deprecation.description == "this function will be removed"
def test_broken_meta() -> None:
with pytest.raises(ParseError):
parse(":")
with pytest.raises(ParseError):
parse(":param herp derp")
with pytest.raises(ParseError):
parse(":param: invalid")
with pytest.raises(ParseError):
parse(":param with too many args: desc")
# these should not raise any errors
parse(":sthstrange: desc")
def test_meta_with_args() -> None:
docstring = parse("""
Short description
:meta ene due rabe: asd
""")
assert docstring.short_description == "Short description"
assert len(docstring.meta) == 1
assert docstring.meta[0].args == ["meta", "ene", "due", "rabe"]
assert docstring.meta[0].description == "asd"
def test_long_description(
source: str,
expected_short_desc: str,
expected_long_desc: str,
expected_blank: bool,
) -> None:
docstring = parse(source)
assert docstring.short_description == expected_short_desc
assert docstring.long_description == expected_long_desc
assert docstring.blank_after_short_description == expected_blank
assert docstring.meta == []
def test_raises() -> None:
docstring = parse("""
Short description
""")
assert len(docstring.raises) == 0
docstring = parse("""
Short description
:raises: description
""")
assert len(docstring.raises) == 1
assert docstring.raises[0].type_name is None
assert docstring.raises[0].description == "description"
docstring = parse("""
Short description
:raises ValueError: description
""")
assert len(docstring.raises) == 1
assert docstring.raises[0].type_name == "ValueError"
assert docstring.raises[0].description == "description"
def test_meta_with_multiline_description() -> None:
docstring = parse("""
Short description
:meta: asd
1
2
3
""")
assert docstring.short_description == "Short description"
assert len(docstring.meta) == 1
assert docstring.meta[0].args == ["meta"]
assert docstring.meta[0].description == "asd\n1\n 2\n3"
def test_meta_newlines(
source: str,
expected_short_desc: T.Optional[str],
expected_long_desc: T.Optional[str],
expected_blank_short_desc: bool,
expected_blank_long_desc: bool,
) -> None:
docstring = parse(source)
assert docstring.short_description == expected_short_desc
assert docstring.long_description == expected_long_desc
assert docstring.blank_after_short_description == expected_blank_short_desc
assert docstring.blank_after_long_description == expected_blank_long_desc
assert len(docstring.meta) == 1
def test_compose(rendering_style: RenderingStyle, expected: str) -> None:
"""Test compose"""
docstring = parse("""
Short description.
Long description.
:param int foo: a description
:param int bar: another description
:return float: a return
""")
assert compose(docstring, rendering_style=rendering_style) == expected
def test_returns() -> None:
"""Test parsing returns."""
docstring = parse("""
Short description
""")
assert docstring.returns is None
assert docstring.many_returns is not None
assert len(docstring.many_returns) == 0
docstring = parse("""
Short description
:returns: description
""")
assert docstring.returns is not None
assert docstring.returns.type_name is None
assert docstring.returns.description == "description"
assert not docstring.returns.is_generator
assert docstring.many_returns == [docstring.returns]
docstring = parse("""
Short description
:returns int: description
""")
assert docstring.returns is not None
assert docstring.returns.type_name == "int"
assert docstring.returns.description == "description"
assert not docstring.returns.is_generator
assert docstring.many_returns == [docstring.returns]
docstring = parse("""
Short description
:returns: description
:rtype: int
""")
assert docstring.returns is not None
assert docstring.returns.type_name == "int"
assert docstring.returns.description == "description"
assert not docstring.returns.is_generator
assert docstring.many_returns == [docstring.returns]
def test_yields() -> None:
docstring = parse("""
Short description
""")
assert docstring.returns is None
docstring = parse("""
Short description
:yields: description
""")
assert docstring.returns is not None
assert docstring.returns.type_name is None
assert docstring.returns.description == "description"
assert docstring.returns.is_generator
docstring = parse("""
Short description
:yields int: description
""")
assert docstring.returns is not None
assert docstring.returns.type_name == "int"
assert docstring.returns.description == "description"
assert docstring.returns.is_generator
def test_multiple_meta() -> None:
docstring = parse("""
Short description
:meta1: asd
1
2
3
:meta2: herp
:meta3: derp
""")
assert docstring.short_description == "Short description"
assert len(docstring.meta) == 3
assert docstring.meta[0].args == ["meta1"]
assert docstring.meta[0].description == "asd\n1\n 2\n3"
assert docstring.meta[1].args == ["meta2"]
assert docstring.meta[1].description == "herp"
assert docstring.meta[2].args == ["meta3"]
assert docstring.meta[2].description == "derp"
def test_short_rtype() -> None:
"""Test abbreviated docstring with only return type information."""
string = "Short description.\n\n:rtype: float"
docstring = parse(string)
rendering_style = RenderingStyle.EXPANDED
assert compose(docstring, rendering_style=rendering_style) == string
def test_short_description(source: str, expected: str) -> None:
docstring = parse(source)
assert docstring.short_description == expected
assert docstring.long_description is None
assert docstring.meta == []
def test_short_description(source: str, expected: str) -> None:
"""Test parsing short description."""
docstring = parse(source)
assert docstring.short_description == expected
assert docstring.long_description is None
assert not docstring.meta
