feat: Support attributes sections for Google-style docstrings

Author: pawamoy

Diff for: src/pytkdocs/parsers/docstrings/base.py

@@ -22,6 +22,22 @@ def __init__(self, annotation: Any, description: str) -> None:
         self.description = description
 
 
+class Attribute(AnnotatedObject):
+    """A helper class to store information about a documented attribute."""
+
+    def __init__(self, name: str, annotation: Any, description: str) -> None:
+        """
+        Initialization method.
+
+        Arguments:
+            name: The attribute's name.
+            annotation: The object's annotation.
+            description: The object's description.
+        """
+        super().__init__(annotation, description)
+        self.name = name
+
+
 class Parameter(AnnotatedObject):
     """A helper class to store information about a signature parameter."""
 
@@ -90,6 +106,7 @@ class Type:
         EXCEPTIONS = "exceptions"
         RETURN = "return"
         EXAMPLES = "examples"
+        ATTRIBUTES = "attributes"
 
     def __init__(self, section_type: str, value: Any) -> None:
         """
@@ -125,7 +142,7 @@ def __init__(self) -> None:
         self.context: dict = {}
         self.errors: List[str] = []
 
-    def parse(self, docstring: str, context: Optional[dict] = None,) -> Tuple[List[Section], List[str]]:
+    def parse(self, docstring: str, context: Optional[dict] = None) -> Tuple[List[Section], List[str]]:
         """
         Parse a docstring and return a list of sections and parsing errors.
 

Diff for: src/pytkdocs/parsers/docstrings/google.py

@@ -2,7 +2,7 @@
 import re
 from typing import Any, List, Optional, Pattern, Sequence, Tuple
 
-from pytkdocs.parsers.docstrings.base import AnnotatedObject, Parameter, Parser, Section, empty
+from pytkdocs.parsers.docstrings.base import AnnotatedObject, Attribute, Parameter, Parser, Section, empty
 
 TITLES_PARAMETERS: Sequence[str] = ("args:", "arguments:", "params:", "parameters:")
 """Titles to match for "parameters" sections."""
@@ -16,6 +16,9 @@
 TITLES_EXAMPLES: Sequence[str] = ("example:", "examples:")
 """Titles to match for "examples" sections."""
 
+TITLES_ATTRIBUTES: Sequence[str] = ("attribute:", "attributes:")
+"""Titles to match for "attributes" sections."""
+
 RE_GOOGLE_STYLE_ADMONITION: Pattern = re.compile(r"^(?P<indent>\s*)(?P<type>[\w-]+):((?:\s+)(?P<title>.+))?$")
 """Regular expressions to match lines starting admonitions, of the form `TYPE: [TITLE]`."""
 
@@ -38,6 +41,8 @@ def parse_sections(self, docstring: str) -> List[Section]:  # noqa: D102
             self.context["signature"] = getattr(self.context["obj"], "signature", None)
         if "annotation" not in self.context:
             self.context["annotation"] = getattr(self.context["obj"], "type", empty)
+        if "attributes" not in self.context:
+            self.context["attributes"] = {}
 
         sections = []
         current_section = []
@@ -55,6 +60,15 @@ def parse_sections(self, docstring: str) -> List[Section]:  # noqa: D102
                     in_code_block = False
                 current_section.append(lines[i])
 
+            elif line_lower in TITLES_ATTRIBUTES:
+                if current_section:
+                    if any(current_section):
+                        sections.append(Section(Section.Type.MARKDOWN, "\n".join(current_section)))
+                    current_section = []
+                section, i = self.read_attributes_section(lines, i + 1)
+                if section:
+                    sections.append(section)
+
             elif line_lower in TITLES_PARAMETERS:
                 if current_section:
                     if any(current_section):
@@ -296,6 +310,46 @@ def read_parameters_section(self, lines: List[str], start_index: int) -> Tuple[O
         self.error(f"Empty parameters section at line {start_index}")
         return None, i
 
+    def read_attributes_section(self, lines: List[str], start_index: int) -> Tuple[Optional[Section], int]:
+        """
+        Parse an "attributes" section.
+
+        Arguments:
+            lines: The parameters block lines.
+            start_index: The line number to start at.
+
+        Returns:
+            A tuple containing a `Section` (or `None`) and the index at which to continue parsing.
+        """
+        attributes = []
+        block, i = self.read_block_items(lines, start_index)
+
+        for attr_line in block:
+            try:
+                name_with_type, description = attr_line.split(":", 1)
+            except ValueError:
+                self.error(f"Failed to get 'name: description' pair from '{attr_line}'")
+                continue
+
+            description = description.lstrip()
+
+            if " " in name_with_type:
+                name, annotation = name_with_type.split(" ", 1)
+                annotation = annotation.strip("()")
+                if annotation.endswith(", optional"):
+                    annotation = annotation[:-10]
+            else:
+                name = name_with_type
+                annotation = self.context["attributes"].get(name, {}).get("annotation", empty)
+
+            attributes.append(Attribute(name=name, annotation=annotation, description=description))
+
+        if attributes:
+            return Section(Section.Type.ATTRIBUTES, attributes), i
+
+        self.error(f"Empty attributes section at line {start_index}")
+        return None, i
+
     def read_exceptions_section(self, lines: List[str], start_index: int) -> Tuple[Optional[Section], int]:
         """
         Parse an "exceptions" section.

Diff for: src/pytkdocs/serializer.py

@@ -9,7 +9,7 @@
 from typing import Any, Optional, Pattern
 
 from pytkdocs.objects import Object, Source
-from pytkdocs.parsers.docstrings.base import AnnotatedObject, Parameter, Section
+from pytkdocs.parsers.docstrings.base import AnnotatedObject, Attribute, Parameter, Section
 
 try:
     from typing import GenericMeta  # python 3.6
@@ -84,6 +84,23 @@ def serialize_annotated_object(obj: AnnotatedObject) -> dict:
     return {"description": obj.description, "annotation": annotation_to_string(obj.annotation)}
 
 
+def serialize_attribute(attribute: Attribute) -> dict:
+    """
+    Serialize an instance of [`Attribute`][pytkdocs.parsers.docstrings.base.Attribute].
+
+    Arguments:
+        attribute: The attribute to serialize.
+
+    Returns:
+        A JSON-serializable dictionary.
+    """
+    return {
+        "name": attribute.name,
+        "description": attribute.description,
+        "annotation": annotation_to_string(attribute.annotation),
+    }
+
+
 def serialize_parameter(parameter: Parameter) -> dict:
     """
     Serialize an instance of [`Parameter`][pytkdocs.parsers.docstrings.base.Parameter].
@@ -166,6 +183,8 @@ def serialize_docstring_section(section: Section) -> dict:
         serialized.update({"value": [serialize_annotated_object(e) for e in section.value]})  # type: ignore
     elif section.type == section.Type.PARAMETERS:
         serialized.update({"value": [serialize_parameter(p) for p in section.value]})  # type: ignore
+    elif section.type == section.Type.ATTRIBUTES:
+        serialized.update({"value": [serialize_attribute(p) for p in section.value]})  # type: ignore
     elif section.type == section.Type.EXAMPLES:
         serialized.update({"value": section.value})  # type: ignore
     return serialized

Diff for: tests/fixtures/docstring_attributes_section.py

@@ -0,0 +1,16 @@
+"""
+Let's describe some attributes.
+
+Attributes:
+    A: Alpha.
+    B (bytes): Beta.
+    C: Gamma.
+    D: Delta.
+    E (float): Epsilon.
+"""
+
+A: int = 0
+B: str = "ŧ"
+C: bool = True
+D = 3.0
+E = None

Diff for: tests/test_parsers/test_docstrings/test_google.py

@@ -4,7 +4,9 @@
 from textwrap import dedent
 
 from pytkdocs.loader import Loader
+from pytkdocs.parsers.docstrings.base import Section
 from pytkdocs.parsers.docstrings.google import Google
+from pytkdocs.serializer import serialize_attribute
 
 
 class DummyObject:
@@ -521,3 +523,22 @@ def f():
     assert sections[2].value == "    AnyLine: ...indented with less than 5 spaces signifies the end of the section."
     assert len(errors) == 1
     assert "should be 5 * 2 = 10 spaces, not 6" in errors[0]
+
+
+def test_parse_module_attributes_section():
+    """Parse attributes section in modules."""
+    loader = Loader()
+    obj = loader.get_object_documentation("tests.fixtures.docstring_attributes_section")
+    assert len(obj.docstring_sections) == 2
+    assert not obj.docstring_errors
+    attr_section = obj.docstring_sections[1]
+    assert attr_section.type == Section.Type.ATTRIBUTES
+    assert len(attr_section.value) == 5
+    expected = [
+        {"name": "A", "annotation": "int", "description": "Alpha."},
+        {"name": "B", "annotation": "bytes", "description": "Beta."},
+        {"name": "C", "annotation": "bool", "description": "Gamma."},
+        {"name": "D", "annotation": "", "description": "Delta."},
+        {"name": "E", "annotation": "float", "description": "Epsilon."},
+    ]
+    assert [serialize_attribute(attr) for attr in attr_section.value] == expected