def test_attributes() -> None: docstring = parse("Short description") assert len(docstring.params) == 0 docstring = parse( """ Short description Attributes ---------- name description 1 priority : int description 2 sender : str, optional description 3 ratio : Optional[float], optional description 4 """ ) 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].is_optional is False assert docstring.params[1].arg_name == "priority" assert docstring.params[1].type_name == "int" assert docstring.params[1].description == "description 2" assert docstring.params[1].is_optional is False 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 is True assert docstring.params[3].arg_name == "ratio" assert docstring.params[3].type_name == "Optional[float]" assert docstring.params[3].description == "description 4" assert docstring.params[3].is_optional is True docstring = parse( """ Short description Attributes ---------- name description 1 with multi-line text priority : int description 2 """ ) assert len(docstring.params) == 2 assert docstring.params[0].arg_name == "name" assert docstring.params[0].type_name is None assert docstring.params[0].description == ( "description 1\n" "with multi-line text" ) assert docstring.params[1].arg_name == "priority" assert docstring.params[1].type_name == "int" assert docstring.params[1].description == "description 2"
def test_params() -> None: """Test parsing params.""" docstring = parse("Short description") assert len(docstring.params) == 0 docstring = parse(""" Short description Parameters ---------- name description 1 priority : int description 2 sender : str, optional description 3 ratio : Optional[float], optional description 4 """) 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 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[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[3].arg_name == "ratio" assert docstring.params[3].type_name == "Optional[float]" assert docstring.params[3].description == "description 4" assert docstring.params[3].is_optional docstring = parse(""" Short description Parameters ---------- name description 1 with multi-line text priority : int description 2 """) assert len(docstring.params) == 2 assert docstring.params[0].arg_name == "name" assert docstring.params[0].type_name is None assert docstring.params[0].description == ( "description 1\nwith multi-line text") assert docstring.params[1].arg_name == "priority" assert docstring.params[1].type_name == "int" assert docstring.params[1].description == "description 2"
def test_returns() -> None: docstring = parse(""" Short description """) assert docstring.returns is None docstring = parse(""" Short description Returns ------- type """) assert docstring.returns is not None assert docstring.returns.type_name == "type" assert docstring.returns.description is None docstring = parse(""" Short description Returns ------- int description """) assert docstring.returns is not None assert docstring.returns.type_name == "int" assert docstring.returns.description == "description" docstring = parse(""" Returns ------- Optional[Mapping[str, List[int]]] A description: with a colon """) assert docstring.returns is not None assert docstring.returns.type_name == "Optional[Mapping[str, List[int]]]" assert docstring.returns.description == "A description: with a colon" docstring = parse(""" Short description Returns ------- int description with much text even some spacing """) assert docstring.returns is not None assert docstring.returns.type_name == "int" assert docstring.returns.description == ("description\n" "with much text\n\n" "even some spacing")
def test_raises() -> None: docstring = parse(""" Short description """) assert len(docstring.raises) == 0 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_default_args(): docstring = parse(""" A sample function A function the demonstrates docstrings Parameters ---------- arg1 : int The firsty arg arg2 : str The second arg arg3 : float, optional The third arg. Default is 1.0. arg4 : Optional[Dict[str, Any]], optional The fourth arg. Defaults to None arg5 : str, optional The fifth arg. Default: DEFAULT_ARGS Returns ------- Mapping[str, Any] The args packed in a mapping """) assert docstring is not None assert len(docstring.params) == 5 arg4 = docstring.params[3] assert arg4.arg_name == "arg4" assert arg4.is_optional assert arg4.type_name == "Optional[Dict[str, Any]]" assert arg4.default == "None" assert arg4.description == "The fourth arg. Defaults to None"
def test_multiple_meta() -> None: """Test parsing multiple meta.""" docstring = parse(""" Short description Parameters ---------- spam asd 1 2 3 Raises ------ bla herp yay derp """) assert docstring.short_description == "Short description" assert len(docstring.meta) == 3 assert docstring.meta[0].args == ["param", "spam"] assert docstring.meta[0].arg_name == "spam" assert docstring.meta[0].description == "asd\n1\n 2\n3" assert docstring.meta[1].args == ["raises", "bla"] assert docstring.meta[1].type_name == "bla" assert docstring.meta[1].description == "herp" assert docstring.meta[2].args == ["raises", "yay"] assert docstring.meta[2].type_name == "yay" assert docstring.meta[2].description == "derp"
def test_other_params() -> None: """Test parsing other parameters.""" docstring = parse(""" Short description Other Parameters ---------------- only_seldom_used_keywords : type, optional Explanation common_parameters_listed_above : type, optional Explanation """) assert len(docstring.meta) == 2 assert docstring.meta[0].args == [ "other_param", "only_seldom_used_keywords", ] assert docstring.meta[0].arg_name == "only_seldom_used_keywords" assert docstring.meta[0].type_name == "type" assert docstring.meta[0].is_optional assert docstring.meta[0].description == "Explanation" assert docstring.meta[1].args == [ "other_param", "common_parameters_listed_above", ]
def test_deprecation( source: str, expected_depr_version: T.Optional[str], expected_depr_desc: T.Optional[str], ) -> None: docstring = parse(source) assert docstring.deprecation is not None assert docstring.deprecation.version == expected_depr_version assert docstring.deprecation.description == expected_depr_desc
def test_warns() -> None: docstring = parse(""" Short description Warns ----- UserWarning description """) assert len(docstring.meta) == 1 assert docstring.meta[0].type_name == "UserWarning" assert docstring.meta[0].description == "description"
def test_examples() -> None: docstring = parse(""" Short description Examples -------- long example more here """) assert len(docstring.meta) == 1 assert docstring.meta[0].description == "long example\n\nmore here"
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_examples( source, expected_results: T.List[T.Tuple[T.Optional[str], str]]) -> None: """Test parsing examples.""" docstring = parse(source) assert len(docstring.meta) == len(expected_results) for meta, expected_result in zip(docstring.meta, expected_results): assert meta.description == expected_result[1] assert len(docstring.examples) == len(expected_results) for example, expected_result in zip(docstring.examples, expected_results): assert example.snippet == expected_result[0] assert example.description == expected_result[1]
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_yields() -> None: docstring = parse(""" Short description Yields ------ int description """) assert len(docstring.meta) == 1 assert docstring.meta[0].args == ["yields"] assert docstring.meta[0].type_name == "int" assert docstring.meta[0].description == "description" assert docstring.meta[0].return_name is None assert docstring.meta[0].is_generator
def test_default_args( source: str, expected_is_optional: bool, expected_type_name: T.Optional[str], expected_default: T.Optional[str], ) -> None: """Test parsing default arguments.""" docstring = parse(source) assert docstring is not None assert len(docstring.params) == 1 arg1 = docstring.params[0] assert arg1.is_optional == expected_is_optional assert arg1.type_name == expected_type_name assert arg1.default == expected_default
def test_meta_with_multiline_description() -> None: docstring = parse(""" Short description Parameters ---------- spam asd 1 2 3 """) assert docstring.short_description == "Short description" assert len(docstring.meta) == 1 assert docstring.meta[0].args == ["param", "spam"] assert docstring.meta[0].arg_name == "spam" assert docstring.meta[0].description == "asd\n1\n 2\n3"
def test_simple_sections() -> None: docstring = parse( """ Short description See Also -------- something : some thing you can also see actually, anything can go in this section Warnings -------- Here be dragons Notes ----- None of this is real References ---------- Cite the relevant literature, e.g. [1]_. You may also cite these references in the notes section above. .. [1] O. McNoleg, "The integration of GIS, remote sensing, expert systems and adaptive co-kriging for environmental habitat modelling of the Highland Haggis using object-oriented, fuzzy-logic and neural-network techniques," Computers & Geosciences, vol. 22, pp. 585-588, 1996. """ ) assert len(docstring.meta) == 4 assert docstring.meta[0].args == ["see_also"] assert docstring.meta[0].description == ( "something : some thing you can also see\n" "actually, anything can go in this section" ) assert docstring.meta[1].args == ["warnings"] assert docstring.meta[1].description == "Here be dragons" assert docstring.meta[2].args == ["notes"] assert docstring.meta[2].description == "None of this is real" assert docstring.meta[3].args == ["references"]
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 ------- type """) assert docstring.returns is not None assert docstring.returns.type_name == "type" assert docstring.returns.description is None assert docstring.many_returns is not None assert len(docstring.many_returns) == 1 assert docstring.many_returns[0] == 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 docstring.many_returns is not None assert len(docstring.many_returns) == 1 assert docstring.many_returns[0] == docstring.returns docstring = parse(""" Returns ------- Optional[Mapping[str, List[int]]] A description: with a colon """) assert docstring.returns is not None assert docstring.returns.type_name == "Optional[Mapping[str, List[int]]]" assert docstring.returns.description == "A description: with a colon" assert docstring.many_returns is not None assert len(docstring.many_returns) == 1 assert docstring.many_returns[0] == docstring.returns docstring = parse(""" Short description Returns ------- int description with much text even some spacing """) assert docstring.returns is not None assert docstring.returns.type_name == "int" assert docstring.returns.description == ( "description\nwith much text\n\neven some spacing") assert docstring.many_returns is not None assert len(docstring.many_returns) == 1 assert docstring.many_returns[0] == docstring.returns docstring = parse(""" Short description Returns ------- a : int description for a b : str description for b """) assert docstring.returns is not None assert docstring.returns.type_name == "int" assert docstring.returns.description == ("description for a") assert docstring.many_returns is not None assert len(docstring.many_returns) == 2 assert docstring.many_returns[0].type_name == "int" assert docstring.many_returns[0].description == "description for a" assert docstring.many_returns[0].return_name == "a" assert docstring.many_returns[1].type_name == "str" assert docstring.many_returns[1].description == "description for b" assert docstring.many_returns[1].return_name == "b"
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
def test_compose(source: str, expected: str) -> None: """Test compose in default mode.""" assert compose(parse(source)) == expected