From a12cca9b80fb2404f7625a3ad052b2b7d3a130d4 Mon Sep 17 00:00:00 2001 From: Carey Metcalfe Date: Fri, 15 Mar 2024 06:32:37 -0400 Subject: [PATCH] parser: add a description property to docstrings Adds the ability to access the full description of a parsed docstring. This is the short description, an optional newline, and the long description added together. --- docstring_parser/common.py | 19 +++++++++++++++++++ .../tests/test_parse_from_object.py | 5 +++++ docstring_parser/tests/test_parser.py | 18 ++++++++++++++++++ docstring_parser/tests/test_rest.py | 12 +++++++++++- 4 files changed, 53 insertions(+), 1 deletion(-) diff --git a/docstring_parser/common.py b/docstring_parser/common.py index e3e5a56..1738e9a 100644 --- a/docstring_parser/common.py +++ b/docstring_parser/common.py @@ -161,6 +161,25 @@ def __init__( self.meta = [] # type: T.List[DocstringMeta] self.style = style # type: T.Optional[DocstringStyle] + @property + def description(self) -> T.Optional[str]: + """Return the full description of the function + + Returns None if the docstring did not include any description + """ + ret = [] + if self.short_description: + ret.append(self.short_description) + if self.blank_after_short_description: + ret.append("") + if self.long_description: + ret.append(self.long_description) + + if not ret: + return None + + return "\n".join(ret) + @property def params(self) -> T.List[DocstringParam]: """Return a list of information on function params.""" diff --git a/docstring_parser/tests/test_parse_from_object.py b/docstring_parser/tests/test_parse_from_object.py index 79ca711..1db37da 100644 --- a/docstring_parser/tests/test_parse_from_object.py +++ b/docstring_parser/tests/test_parse_from_object.py @@ -37,6 +37,7 @@ class StandardCase: assert docstring.short_description == "Short description" assert docstring.long_description == "Long description" + assert docstring.description == "Short description\nLong description" assert len(docstring.params) == 2 assert docstring.params[0].arg_name == "attr_one" assert docstring.params[0].type_name == "str" @@ -57,6 +58,7 @@ class WithoutType: # pylint: disable=missing-class-docstring assert docstring.short_description is None assert docstring.long_description is None + assert docstring.description is None assert len(docstring.params) == 1 assert docstring.params[0].arg_name == "attr_one" assert docstring.params[0].type_name is None @@ -78,6 +80,8 @@ class WithoutSource: docstring = parse_from_object(WithoutSource) assert docstring.short_description == "Short description" + assert docstring.long_description is None + assert docstring.description == "Short description" assert len(docstring.params) == 0 @@ -95,6 +99,7 @@ def a_function(param1: str, param2: int = 2): docstring = parse_from_object(a_function) assert docstring.short_description == "Short description" + assert docstring.description == "Short description" assert len(docstring.params) == 2 assert docstring.params[0].arg_name == "param1" assert docstring.params[0].type_name is None diff --git a/docstring_parser/tests/test_parser.py b/docstring_parser/tests/test_parser.py index 7e007b1..fcb78bc 100644 --- a/docstring_parser/tests/test_parser.py +++ b/docstring_parser/tests/test_parser.py @@ -31,6 +31,12 @@ def test_rest() -> None: "Causing people to indent:\n\n" " A lot sometimes" ) + assert docstring.description == ( + "Short description\n\n" + "Long description\n\n" + "Causing people to indent:\n\n" + " A lot sometimes" + ) assert len(docstring.params) == 3 assert docstring.params[0].arg_name == "spam" assert docstring.params[0].type_name is None @@ -83,6 +89,12 @@ def test_google() -> None: "Causing people to indent:\n\n" " A lot sometimes" ) + assert docstring.description == ( + "Short description\n\n" + "Long description\n\n" + "Causing people to indent:\n\n" + " A lot sometimes" + ) assert len(docstring.params) == 3 assert docstring.params[0].arg_name == "spam" assert docstring.params[0].type_name is None @@ -157,6 +169,12 @@ def test_numpydoc() -> None: "Causing people to indent:\n\n" " A lot sometimes" ) + assert docstring.description == ( + "Short description\n\n" + "Long description\n\n" + "Causing people to indent:\n\n" + " A lot sometimes" + ) assert len(docstring.params) == 4 assert docstring.params[0].arg_name == "spam" assert docstring.params[0].type_name is None diff --git a/docstring_parser/tests/test_rest.py b/docstring_parser/tests/test_rest.py index 9ad9c2b..7f85085 100644 --- a/docstring_parser/tests/test_rest.py +++ b/docstring_parser/tests/test_rest.py @@ -20,6 +20,7 @@ def test_short_description(source: str, expected: str) -> None: """Test parsing short description.""" docstring = parse(source) assert docstring.short_description == expected + assert docstring.description == expected assert docstring.long_description is None assert not docstring.meta @@ -103,7 +104,8 @@ def test_long_description( @pytest.mark.parametrize( "source, expected_short_desc, expected_long_desc, " - "expected_blank_short_desc, expected_blank_long_desc", + "expected_blank_short_desc, expected_blank_long_desc, " + "expected_full_desc", [ ( """ @@ -114,6 +116,7 @@ def test_long_description( None, False, False, + "Short description", ), ( """ @@ -125,6 +128,7 @@ def test_long_description( "Long description", False, False, + "Short description\nLong description", ), ( """ @@ -137,6 +141,7 @@ def test_long_description( "First line\n Second line", False, False, + "Short description\nFirst line\n Second line", ), ( """ @@ -150,6 +155,7 @@ def test_long_description( "First line\n Second line", True, False, + "Short description\n\nFirst line\n Second line", ), ( """ @@ -164,6 +170,7 @@ def test_long_description( "First line\n Second line", True, True, + "Short description\n\nFirst line\n Second line", ), ( """ @@ -173,6 +180,7 @@ def test_long_description( None, False, False, + None, ), ], ) @@ -182,6 +190,7 @@ def test_meta_newlines( expected_long_desc: T.Optional[str], expected_blank_short_desc: bool, expected_blank_long_desc: bool, + expected_full_desc: T.Optional[str], ) -> None: """Test parsing newlines around description sections.""" docstring = parse(source) @@ -189,6 +198,7 @@ def test_meta_newlines( 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 docstring.description == expected_full_desc assert len(docstring.meta) == 1