1089 lines
28 KiB
Python
1089 lines
28 KiB
Python
"""Tests for numpydoc-style docstring routines."""
|
|
|
|
import typing as T
|
|
|
|
import pytest
|
|
from docstring_parser.numpydoc import compose, parse
|
|
|
|
|
|
@pytest.mark.parametrize(
|
|
"source, expected",
|
|
[
|
|
("", None),
|
|
("\n", None),
|
|
("Short description", "Short description"),
|
|
("\nShort description\n", "Short description"),
|
|
("\n Short description\n", "Short description"),
|
|
],
|
|
)
|
|
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
|
|
|
|
|
|
@pytest.mark.parametrize(
|
|
"source, expected_short_desc, expected_long_desc, expected_blank",
|
|
[
|
|
(
|
|
"Short description\n\nLong description",
|
|
"Short description",
|
|
"Long description",
|
|
True,
|
|
),
|
|
(
|
|
"""
|
|
Short description
|
|
|
|
Long description
|
|
""",
|
|
"Short description",
|
|
"Long description",
|
|
True,
|
|
),
|
|
(
|
|
"""
|
|
Short description
|
|
|
|
Long description
|
|
Second line
|
|
""",
|
|
"Short description",
|
|
"Long description\nSecond line",
|
|
True,
|
|
),
|
|
(
|
|
"Short description\nLong description",
|
|
"Short description",
|
|
"Long description",
|
|
False,
|
|
),
|
|
(
|
|
"""
|
|
Short description
|
|
Long description
|
|
""",
|
|
"Short description",
|
|
"Long description",
|
|
False,
|
|
),
|
|
(
|
|
"\nShort description\nLong description\n",
|
|
"Short description",
|
|
"Long description",
|
|
False,
|
|
),
|
|
(
|
|
"""
|
|
Short description
|
|
Long description
|
|
Second line
|
|
""",
|
|
"Short description",
|
|
"Long description\nSecond line",
|
|
False,
|
|
),
|
|
],
|
|
)
|
|
def test_long_description(
|
|
source: str,
|
|
expected_short_desc: str,
|
|
expected_long_desc: str,
|
|
expected_blank: bool,
|
|
) -> None:
|
|
"""Test parsing long description."""
|
|
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 not docstring.meta
|
|
|
|
|
|
@pytest.mark.parametrize(
|
|
"source, expected_short_desc, expected_long_desc, "
|
|
"expected_blank_short_desc, expected_blank_long_desc",
|
|
[
|
|
(
|
|
"""
|
|
Short description
|
|
Parameters
|
|
----------
|
|
asd
|
|
""",
|
|
"Short description",
|
|
None,
|
|
False,
|
|
False,
|
|
),
|
|
(
|
|
"""
|
|
Short description
|
|
Long description
|
|
Parameters
|
|
----------
|
|
asd
|
|
""",
|
|
"Short description",
|
|
"Long description",
|
|
False,
|
|
False,
|
|
),
|
|
(
|
|
"""
|
|
Short description
|
|
First line
|
|
Second line
|
|
Parameters
|
|
----------
|
|
asd
|
|
""",
|
|
"Short description",
|
|
"First line\n Second line",
|
|
False,
|
|
False,
|
|
),
|
|
(
|
|
"""
|
|
Short description
|
|
|
|
First line
|
|
Second line
|
|
Parameters
|
|
----------
|
|
asd
|
|
""",
|
|
"Short description",
|
|
"First line\n Second line",
|
|
True,
|
|
False,
|
|
),
|
|
(
|
|
"""
|
|
Short description
|
|
|
|
First line
|
|
Second line
|
|
|
|
Parameters
|
|
----------
|
|
asd
|
|
""",
|
|
"Short description",
|
|
"First line\n Second line",
|
|
True,
|
|
True,
|
|
),
|
|
(
|
|
"""
|
|
Parameters
|
|
----------
|
|
asd
|
|
""",
|
|
None,
|
|
None,
|
|
False,
|
|
False,
|
|
),
|
|
],
|
|
)
|
|
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:
|
|
"""Test parsing newlines around description sections."""
|
|
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_meta_with_multiline_description() -> None:
|
|
"""Test parsing multiline meta documentation."""
|
|
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"
|
|
|
|
|
|
@pytest.mark.parametrize(
|
|
"source, expected_is_optional, expected_type_name, expected_default",
|
|
[
|
|
(
|
|
"""
|
|
Parameters
|
|
----------
|
|
arg1 : int
|
|
The first arg
|
|
""",
|
|
False,
|
|
"int",
|
|
None,
|
|
),
|
|
(
|
|
"""
|
|
Parameters
|
|
----------
|
|
arg2 : str
|
|
The second arg
|
|
""",
|
|
False,
|
|
"str",
|
|
None,
|
|
),
|
|
(
|
|
"""
|
|
Parameters
|
|
----------
|
|
arg3 : float, optional
|
|
The third arg. Default is 1.0.
|
|
""",
|
|
True,
|
|
"float",
|
|
"1.0",
|
|
),
|
|
(
|
|
"""
|
|
Parameters
|
|
----------
|
|
arg4 : Optional[Dict[str, Any]], optional
|
|
The fourth arg. Defaults to None
|
|
""",
|
|
True,
|
|
"Optional[Dict[str, Any]]",
|
|
"None",
|
|
),
|
|
(
|
|
"""
|
|
Parameters
|
|
----------
|
|
arg5 : str, optional
|
|
The fifth arg. Default: DEFAULT_ARGS
|
|
""",
|
|
True,
|
|
"str",
|
|
"DEFAULT_ARGS",
|
|
),
|
|
(
|
|
"""
|
|
Parameters
|
|
----------
|
|
parameter_without_default : int
|
|
The parameter_without_default is required.
|
|
""",
|
|
False,
|
|
"int",
|
|
None,
|
|
),
|
|
],
|
|
)
|
|
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_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_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_attributes() -> None:
|
|
"""Test parsing attributes."""
|
|
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 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
|
|
|
|
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\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_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_yields() -> None:
|
|
"""Test parsing yields."""
|
|
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_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_raises() -> None:
|
|
"""Test parsing raises."""
|
|
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_warns() -> None:
|
|
"""Test parsing warns."""
|
|
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_simple_sections() -> None:
|
|
"""Test parsing simple sections."""
|
|
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"]
|
|
|
|
|
|
@pytest.mark.parametrize(
|
|
"source, expected_results",
|
|
[
|
|
(
|
|
"Description\nExamples\n--------\nlong example\n\nmore here",
|
|
[
|
|
(None, "long example\n\nmore here"),
|
|
],
|
|
),
|
|
(
|
|
"Description\nExamples\n--------\n>>> test",
|
|
[
|
|
(">>> test", ""),
|
|
],
|
|
),
|
|
(
|
|
"Description\nExamples\n--------\n>>> testa\n>>> testb",
|
|
[
|
|
(">>> testa\n>>> testb", ""),
|
|
],
|
|
),
|
|
(
|
|
"Description\nExamples\n--------\n>>> test1\ndesc1",
|
|
[
|
|
(">>> test1", "desc1"),
|
|
],
|
|
),
|
|
(
|
|
"Description\nExamples\n--------\n"
|
|
">>> test1a\n>>> test1b\ndesc1a\ndesc1b",
|
|
[
|
|
(">>> test1a\n>>> test1b", "desc1a\ndesc1b"),
|
|
],
|
|
),
|
|
(
|
|
"Description\nExamples\n--------\n"
|
|
">>> test1\ndesc1\n>>> test2\ndesc2",
|
|
[
|
|
(">>> test1", "desc1"),
|
|
(">>> test2", "desc2"),
|
|
],
|
|
),
|
|
(
|
|
"Description\nExamples\n--------\n"
|
|
">>> test1a\n>>> test1b\ndesc1a\ndesc1b\n"
|
|
">>> test2a\n>>> test2b\ndesc2a\ndesc2b\n",
|
|
[
|
|
(">>> test1a\n>>> test1b", "desc1a\ndesc1b"),
|
|
(">>> test2a\n>>> test2b", "desc2a\ndesc2b"),
|
|
],
|
|
),
|
|
(
|
|
"Description\nExamples\n--------\n"
|
|
" >>> test1a\n >>> test1b\n desc1a\n desc1b\n"
|
|
" >>> test2a\n >>> test2b\n desc2a\n desc2b\n",
|
|
[
|
|
(">>> test1a\n>>> test1b", "desc1a\ndesc1b"),
|
|
(">>> test2a\n>>> test2b", "desc2a\ndesc2b"),
|
|
],
|
|
),
|
|
],
|
|
)
|
|
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]
|
|
|
|
|
|
@pytest.mark.parametrize(
|
|
"source, expected_depr_version, expected_depr_desc",
|
|
[
|
|
(
|
|
"Short description\n\n.. deprecated:: 1.6.0\n This is busted!",
|
|
"1.6.0",
|
|
"This is busted!",
|
|
),
|
|
(
|
|
(
|
|
"Short description\n\n"
|
|
".. deprecated:: 1.6.0\n"
|
|
" This description has\n"
|
|
" multiple lines!"
|
|
),
|
|
"1.6.0",
|
|
"This description has\nmultiple lines!",
|
|
),
|
|
("Short description\n\n.. deprecated:: 1.6.0", "1.6.0", None),
|
|
(
|
|
"Short description\n\n.. deprecated::\n No version!",
|
|
None,
|
|
"No version!",
|
|
),
|
|
],
|
|
)
|
|
def test_deprecation(
|
|
source: str,
|
|
expected_depr_version: T.Optional[str],
|
|
expected_depr_desc: T.Optional[str],
|
|
) -> None:
|
|
"""Test parsing deprecation notes."""
|
|
docstring = parse(source)
|
|
|
|
assert docstring.deprecation is not None
|
|
assert docstring.deprecation.version == expected_depr_version
|
|
assert docstring.deprecation.description == expected_depr_desc
|
|
|
|
|
|
@pytest.mark.parametrize(
|
|
"source, expected",
|
|
[
|
|
("", ""),
|
|
("\n", ""),
|
|
("Short description", "Short description"),
|
|
("\nShort description\n", "Short description"),
|
|
("\n Short description\n", "Short description"),
|
|
(
|
|
"Short description\n\nLong description",
|
|
"Short description\n\nLong description",
|
|
),
|
|
(
|
|
"""
|
|
Short description
|
|
|
|
Long description
|
|
""",
|
|
"Short description\n\nLong description",
|
|
),
|
|
(
|
|
"""
|
|
Short description
|
|
|
|
Long description
|
|
Second line
|
|
""",
|
|
"Short description\n\nLong description\nSecond line",
|
|
),
|
|
(
|
|
"Short description\nLong description",
|
|
"Short description\nLong description",
|
|
),
|
|
(
|
|
"""
|
|
Short description
|
|
Long description
|
|
""",
|
|
"Short description\nLong description",
|
|
),
|
|
(
|
|
"\nShort description\nLong description\n",
|
|
"Short description\nLong description",
|
|
),
|
|
(
|
|
"""
|
|
Short description
|
|
Long description
|
|
Second line
|
|
""",
|
|
"Short description\nLong description\nSecond line",
|
|
),
|
|
(
|
|
"""
|
|
Short description
|
|
Meta:
|
|
-----
|
|
asd
|
|
""",
|
|
"Short description\nMeta:\n-----\n asd",
|
|
),
|
|
(
|
|
"""
|
|
Short description
|
|
Long description
|
|
Meta:
|
|
-----
|
|
asd
|
|
""",
|
|
"Short description\n"
|
|
"Long description\n"
|
|
"Meta:\n"
|
|
"-----\n"
|
|
" asd",
|
|
),
|
|
(
|
|
"""
|
|
Short description
|
|
First line
|
|
Second line
|
|
Meta:
|
|
-----
|
|
asd
|
|
""",
|
|
"Short description\n"
|
|
"First line\n"
|
|
" Second line\n"
|
|
"Meta:\n"
|
|
"-----\n"
|
|
" asd",
|
|
),
|
|
(
|
|
"""
|
|
Short description
|
|
|
|
First line
|
|
Second line
|
|
Meta:
|
|
-----
|
|
asd
|
|
""",
|
|
"Short description\n"
|
|
"\n"
|
|
"First line\n"
|
|
" Second line\n"
|
|
"Meta:\n"
|
|
"-----\n"
|
|
" asd",
|
|
),
|
|
(
|
|
"""
|
|
Short description
|
|
|
|
First line
|
|
Second line
|
|
|
|
Meta:
|
|
-----
|
|
asd
|
|
""",
|
|
"Short description\n"
|
|
"\n"
|
|
"First line\n"
|
|
" Second line\n"
|
|
"\n"
|
|
"Meta:\n"
|
|
"-----\n"
|
|
" asd",
|
|
),
|
|
(
|
|
"""
|
|
Short description
|
|
|
|
Meta:
|
|
-----
|
|
asd
|
|
1
|
|
2
|
|
3
|
|
""",
|
|
"Short description\n"
|
|
"\n"
|
|
"Meta:\n"
|
|
"-----\n"
|
|
" asd\n"
|
|
" 1\n"
|
|
" 2\n"
|
|
" 3",
|
|
),
|
|
(
|
|
"""
|
|
Short description
|
|
|
|
Meta1:
|
|
------
|
|
asd
|
|
1
|
|
2
|
|
3
|
|
Meta2:
|
|
------
|
|
herp
|
|
Meta3:
|
|
------
|
|
derp
|
|
""",
|
|
"Short description\n"
|
|
"\n"
|
|
"Meta1:\n"
|
|
"------\n"
|
|
" asd\n"
|
|
" 1\n"
|
|
" 2\n"
|
|
" 3\n"
|
|
"Meta2:\n"
|
|
"------\n"
|
|
" herp\n"
|
|
"Meta3:\n"
|
|
"------\n"
|
|
" derp",
|
|
),
|
|
(
|
|
"""
|
|
Short description
|
|
|
|
Parameters:
|
|
-----------
|
|
name
|
|
description 1
|
|
priority: int
|
|
description 2
|
|
sender: str, optional
|
|
description 3
|
|
message: str, optional
|
|
description 4, defaults to 'hello'
|
|
multiline: str, optional
|
|
long description 5,
|
|
defaults to 'bye'
|
|
""",
|
|
"Short description\n"
|
|
"\n"
|
|
"Parameters:\n"
|
|
"-----------\n"
|
|
" name\n"
|
|
" description 1\n"
|
|
" priority: int\n"
|
|
" description 2\n"
|
|
" sender: str, optional\n"
|
|
" description 3\n"
|
|
" message: str, optional\n"
|
|
" description 4, defaults to 'hello'\n"
|
|
" multiline: str, optional\n"
|
|
" long description 5,\n"
|
|
" defaults to 'bye'",
|
|
),
|
|
(
|
|
"""
|
|
Short description
|
|
Raises:
|
|
-------
|
|
ValueError
|
|
description
|
|
""",
|
|
"Short description\n"
|
|
"Raises:\n"
|
|
"-------\n"
|
|
" ValueError\n"
|
|
" description",
|
|
),
|
|
(
|
|
"""
|
|
Description
|
|
Examples:
|
|
--------
|
|
>>> test1a
|
|
>>> test1b
|
|
desc1a
|
|
desc1b
|
|
>>> test2a
|
|
>>> test2b
|
|
desc2a
|
|
desc2b
|
|
""",
|
|
"Description\n"
|
|
"Examples:\n"
|
|
"--------\n"
|
|
">>> test1a\n"
|
|
">>> test1b\n"
|
|
"desc1a\n"
|
|
"desc1b\n"
|
|
">>> test2a\n"
|
|
">>> test2b\n"
|
|
"desc2a\n"
|
|
"desc2b",
|
|
),
|
|
],
|
|
)
|
|
def test_compose(source: str, expected: str) -> None:
|
|
"""Test compose in default mode."""
|
|
assert compose(parse(source)) == expected
|