Add support for "Attributes" docstring section

Author: jsh9

CHANGELOG.md

@@ -1,3 +1,8 @@
+# (Fork) 0.0.7 (2024-06-22)
+
+- Made "Attributes" a separate section from "Parameters" (for Google, Numpy, and Sphinx
+  styles) 
+
 # (Fork) 0.0.6 (2024-06-22)
 
 - Merged in the latest changes from upstream (version 0.16)

docstring_parser/common.py

@@ -2,12 +2,15 @@
 import enum
 import typing as T
 
+ATTR_KEYWORDS = {
+    "attr",
+    "attribute",
+}
 PARAM_KEYWORDS = {
     "param",
     "parameter",
     "arg",
     "argument",
-    "attribute",
     "key",
     "keyword",
 }
@@ -62,6 +65,9 @@ def __init__(
         self.args = args
         self.description = description
 
+    def __repr__(self) -> str:
+        return str(self.__dict__)
+
 
 class DocstringParam(DocstringMeta):
     """DocstringMeta symbolizing :param metadata."""
@@ -83,6 +89,26 @@ def __init__(
         self.default = default
 
 
+class DocstringAttr(DocstringMeta):
+    """DocstringMeta symbolizing :attr metadata."""
+
+    def __init__(
+        self,
+        args: T.List[str],
+        description: T.Optional[str],
+        arg_name: str,
+        type_name: T.Optional[str],
+        is_optional: T.Optional[bool],
+        default: T.Optional[str],
+    ) -> None:
+        """Initialize self."""
+        super().__init__(args, description)
+        self.arg_name = arg_name
+        self.type_name = type_name
+        self.is_optional = is_optional
+        self.default = default
+
+
 class DocstringReturns(DocstringMeta):
     """DocstringMeta symbolizing :returns metadata."""
 
@@ -179,6 +205,9 @@ def __init__(
         self.meta = []  # type: T.List[DocstringMeta]
         self.style = style  # type: T.Optional[DocstringStyle]
 
+    def __repr__(self) -> str:
+        return str(self.__dict__)
+
     @property
     def description(self) -> T.Optional[str]:
         """Return the full description of the function
@@ -198,6 +227,11 @@ def description(self) -> T.Optional[str]:
 
         return "\n".join(ret)
 
+    @property
+    def attrs(self) -> T.List[DocstringAttr]:
+        """Return a list of information on class attributes"""
+        return [item for item in self.meta if isinstance(item, DocstringAttr)]
+
     @property
     def params(self) -> T.List[DocstringParam]:
         """Return a list of information on function params."""

docstring_parser/google.py

@@ -7,12 +7,14 @@
 from enum import IntEnum
 
 from .common import (
+    ATTR_KEYWORDS,
     EXAMPLES_KEYWORDS,
     PARAM_KEYWORDS,
     RAISES_KEYWORDS,
     RETURNS_KEYWORDS,
     YIELDS_KEYWORDS,
     Docstring,
+    DocstringAttr,
     DocstringExample,
     DocstringMeta,
     DocstringParam,
@@ -146,15 +148,15 @@ def _build_single_meta(section: Section, desc: str) -> DocstringMeta:
             return DocstringExample(
                 args=[section.key], snippet=None, description=desc
             )
-        if section.key in PARAM_KEYWORDS:
+        if section.key in PARAM_KEYWORDS | ATTR_KEYWORDS:
             raise ParseError("Expected paramenter name.")
         return DocstringMeta(args=[section.key], description=desc)
 
     @staticmethod
     def _build_multi_meta(
         section: Section, before: str, desc: str
     ) -> DocstringMeta:
-        if section.key in PARAM_KEYWORDS:
+        if section.key in PARAM_KEYWORDS | ATTR_KEYWORDS:
             match = GOOGLE_TYPED_ARG_REGEX.match(before)
             if match:
                 arg_name, type_name = match.group(1, 2)
@@ -173,7 +175,13 @@ def _build_multi_meta(
             match = GOOGLE_ARG_DESC_REGEX.match(desc)
             default = match.group(1) if match else None
 
-            return DocstringParam(
+            DocstringSectionType = (
+                DocstringParam
+                if section.key in PARAM_KEYWORDS
+                else DocstringAttr
+            )
+
+            return DocstringSectionType(
                 args=[section.key, before],
                 description=desc,
                 arg_name=arg_name,

docstring_parser/numpydoc.py

@@ -11,6 +11,7 @@
 
 from .common import (
     Docstring,
+    DocstringAttr,
     DocstringDeprecated,
     DocstringExample,
     DocstringMeta,
@@ -160,6 +161,31 @@ def _parse_item(self, key: str, value: str) -> DocstringParam:
         )
 
 
+class AttrSection(ParamSection):
+    """Parser for numpydoc attribute sections.
+
+    Note: the official Numpy docstring guide doesn't explicitly allow
+    an "Attributes" section (it only states a "Parameters" section), but
+    the Google style explicitly offers an "Attributes" section (see
+    https://google.github.io/styleguide/pyguide.html#s3.8.4-comments-in-doc-strings).
+    That's why we added this for Numpy style.
+    """
+
+    def _parse_item(self, key: str, value: str) -> DocstringAttr:
+        docstringParam: DocstringParam = super()._parse_item(
+            key=key,
+            value=value,
+        )
+        return DocstringAttr(
+            args=docstringParam.args,
+            description=docstringParam.description,
+            arg_name=docstringParam.arg_name,
+            type_name=docstringParam.type_name,
+            is_optional=docstringParam.is_optional,
+            default=docstringParam.default,
+        )
+
+
 class RaisesSection(_KVSection):
     """Parser for numpydoc raises sections.
 
@@ -296,8 +322,8 @@ def parse(self, text: str) -> T.Iterable[DocstringMeta]:
     RaisesSection("Raise", "raises"),
     RaisesSection("Warns", "warns"),
     RaisesSection("Warn", "warns"),
-    ParamSection("Attributes", "attribute"),
-    ParamSection("Attribute", "attribute"),
+    AttrSection("Attributes", "attribute"),
+    AttrSection("Attribute", "attribute"),
     ReturnsSection("Returns", "returns"),
     ReturnsSection("Return", "returns"),
     YieldsSection("Yields", "yields"),

docstring_parser/rest.py

@@ -6,11 +6,13 @@
 
 from .common import (
     DEPRECATION_KEYWORDS,
+    ATTR_KEYWORDS,
     PARAM_KEYWORDS,
     RAISES_KEYWORDS,
     RETURNS_KEYWORDS,
     YIELDS_KEYWORDS,
     Docstring,
+    DocstringAttr,
     DocstringDeprecated,
     DocstringMeta,
     DocstringParam,
@@ -26,7 +28,7 @@
 def _build_meta(args: T.List[str], desc: str) -> DocstringMeta:
     key = args[0]
 
-    if key in PARAM_KEYWORDS:
+    if key in PARAM_KEYWORDS | ATTR_KEYWORDS:
         if len(args) == 3:
             key, type_name, arg_name = args
             if type_name.endswith("?"):
@@ -46,7 +48,11 @@ def _build_meta(args: T.List[str], desc: str) -> DocstringMeta:
         match = re.match(r".*defaults to (.+)", desc, flags=re.DOTALL)
         default = match.group(1).rstrip(".") if match else None
 
-        return DocstringParam(
+        DocstringSectionType = (
+            DocstringParam if key in PARAM_KEYWORDS else DocstringAttr
+        )
+
+        return DocstringSectionType(
             args=args,
             description=desc,
             arg_name=arg_name,
@@ -176,7 +182,7 @@ def parse(text: str) -> Docstring:
             ret.meta.append(_build_meta(args, desc))
 
     for meta in ret.meta:
-        if isinstance(meta, DocstringParam):
+        if isinstance(meta, (DocstringParam, DocstringAttr)):
             meta.type_name = meta.type_name or types.get(meta.arg_name)
         elif isinstance(meta, DocstringReturns):
             meta.type_name = meta.type_name or rtypes.get(meta.return_name)

docstring_parser/tests/test_google.py

@@ -447,7 +447,7 @@ def test_params() -> None:
 def test_attributes() -> None:
     """Test parsing attributes."""
     docstring = parse("Short description")
-    assert len(docstring.params) == 0
+    assert len(docstring.attrs) == 0
 
     docstring = parse(
         """
@@ -460,23 +460,24 @@ def test_attributes() -> None:
             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
+    assert len(docstring.params) == 0  # they are under a new section "attrs"
+    assert len(docstring.attrs) == 4
+    assert docstring.attrs[0].arg_name == "name"
+    assert docstring.attrs[0].type_name is None
+    assert docstring.attrs[0].description == "description 1"
+    assert not docstring.attrs[0].is_optional
+    assert docstring.attrs[1].arg_name == "priority"
+    assert docstring.attrs[1].type_name == "int"
+    assert docstring.attrs[1].description == "description 2"
+    assert not docstring.attrs[1].is_optional
+    assert docstring.attrs[2].arg_name == "sender"
+    assert docstring.attrs[2].type_name == "str"
+    assert docstring.attrs[2].description == "description 3"
+    assert docstring.attrs[2].is_optional
+    assert docstring.attrs[3].arg_name == "ratio"
+    assert docstring.attrs[3].type_name == "Optional[float]"
+    assert docstring.attrs[3].description == "description 4"
+    assert docstring.attrs[3].is_optional
 
     docstring = parse(
         """
@@ -488,15 +489,16 @@ def test_attributes() -> None:
             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 == (
+    assert len(docstring.params) == 0
+    assert len(docstring.attrs) == 2
+    assert docstring.attrs[0].arg_name == "name"
+    assert docstring.attrs[0].type_name is None
+    assert docstring.attrs[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"
+    assert docstring.attrs[1].arg_name == "priority"
+    assert docstring.attrs[1].type_name == "int"
+    assert docstring.attrs[1].description == "description 2"
 
 
 def test_returns() -> None:

docstring_parser/tests/test_numpydoc.py

@@ -415,7 +415,7 @@ def test_params() -> None:
 def test_attributes() -> None:
     """Test parsing attributes."""
     docstring = parse("Short description")
-    assert len(docstring.params) == 0
+    assert len(docstring.attrs) == 0
 
     docstring = parse(
         """
@@ -433,23 +433,24 @@ def test_attributes() -> None:
             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
+    assert len(docstring.params) == 0
+    assert len(docstring.attrs) == 4
+    assert docstring.attrs[0].arg_name == "name"
+    assert docstring.attrs[0].type_name is None
+    assert docstring.attrs[0].description == "description 1"
+    assert not docstring.attrs[0].is_optional
+    assert docstring.attrs[1].arg_name == "priority"
+    assert docstring.attrs[1].type_name == "int"
+    assert docstring.attrs[1].description == "description 2"
+    assert not docstring.attrs[1].is_optional
+    assert docstring.attrs[2].arg_name == "sender"
+    assert docstring.attrs[2].type_name == "str"
+    assert docstring.attrs[2].description == "description 3"
+    assert docstring.attrs[2].is_optional
+    assert docstring.attrs[3].arg_name == "ratio"
+    assert docstring.attrs[3].type_name == "Optional[float]"
+    assert docstring.attrs[3].description == "description 4"
+    assert docstring.attrs[3].is_optional
 
     docstring = parse(
         """
@@ -464,15 +465,16 @@ def test_attributes() -> None:
             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 == (
+    assert len(docstring.params) == 0
+    assert len(docstring.attrs) == 2
+    assert docstring.attrs[0].arg_name == "name"
+    assert docstring.attrs[0].type_name is None
+    assert docstring.attrs[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"
+    assert docstring.attrs[1].type_name == "int"
+    assert docstring.attrs[1].arg_name == "priority"
+    assert docstring.attrs[1].description == "description 2"
 
 
 def test_other_params() -> None: