Merge pull request #40 from AntoineD/fix-duplicated-attr

Fix duplicated section items with complex class hierarchy

Author: rsokl

src/custom_inherit/_doc_parse_tools/napoleon_parse_tools.py

@@ -3,6 +3,8 @@
 from collections import OrderedDict
 from inspect import cleandoc
 
+from . import section_items
+
 __all__ = ["merge_google_napoleon_docs", "merge_numpy_napoleon_docs"]
 
 
@@ -53,6 +55,8 @@ def parse_napoleon_doc(doc, style):
 
     doc_sections = OrderedDict([(key, None) for key in napoleon_sections])
 
+    section_items.set_defaults(doc_sections)
+
     if not doc:
         return doc_sections
 
@@ -84,6 +88,9 @@ def parse_napoleon_doc(doc, style):
         except StopIteration:
             doc_sections[aliases.get(key, key)] = "\n".join(body)
             break
+
+    section_items.parse(doc_sections)
+
     return doc_sections
 
 
@@ -109,7 +116,7 @@ def merge_section(key, prnt_sec, child_sec, style, merge_within_sections=False):
         "Examples",
     ]
 
-    if prnt_sec is None and child_sec is None:
+    if not prnt_sec and not child_sec:
         return None
 
     assert style in ("google", "numpy")
@@ -121,7 +128,11 @@ def merge_section(key, prnt_sec, child_sec, style, merge_within_sections=False):
             header = "\n".join((key, "".join("-" for i in range(len(key))), ""))
         else:
             header = "\n".join((key + ":", ""))
-    if merge_within_sections and key not in napoleon_sections_that_cant_merge:
+
+    if key in section_items.SECTION_NAMES:
+        body = section_items.merge(prnt_sec, child_sec, merge_within_sections, style)
+
+    elif merge_within_sections and key not in napoleon_sections_that_cant_merge:
         if child_sec is None:
             body = prnt_sec
         elif prnt_sec is None:

src/custom_inherit/_doc_parse_tools/numpy_parse_tools.py

@@ -3,6 +3,8 @@
 from collections import OrderedDict
 from inspect import cleandoc
 
+from . import section_items
+
 __all__ = ["merge_numpy_docs"]
 
 
@@ -37,6 +39,8 @@ def parse_numpy_doc(doc):
         ]
     )
 
+    section_items.set_defaults(doc_sections)
+
     if not doc:
         return doc_sections
 
@@ -59,6 +63,8 @@ def parse_numpy_doc(doc):
             doc_sections[key] = "\n".join(body)
             break
 
+    section_items.parse(doc_sections)
+
     return doc_sections
 
 
@@ -85,15 +91,18 @@ def merge_section(key, prnt_sec, child_sec, merge_within_sections=False):
         "Examples"
     ]
 
-    if prnt_sec is None and child_sec is None:
+    if not prnt_sec and not child_sec:
         return None
 
     if key == "Short Summary":
         header = ""
     else:
         header = "\n".join((key, "".join("-" for i in range(len(key))), ""))
 
-    if merge_within_sections and key not in doc_sections_that_cant_merge:
+    if key in section_items.SECTION_NAMES:
+        body = section_items.merge(prnt_sec, child_sec, merge_within_sections, "numpy")
+
+    elif merge_within_sections and key not in doc_sections_that_cant_merge:
         if child_sec is None:
             body = prnt_sec
         elif prnt_sec is None:

src/custom_inherit/_doc_parse_tools/section_items.py

@@ -0,0 +1,96 @@
+"""This module handles sections with items."""
+
+from collections import OrderedDict
+import inspect
+import re
+
+try:
+    from textwrap import indent
+except ImportError:
+    # for Python < 3.3
+    def indent(text, padding):
+        return ''.join(padding+line for line in text.splitlines(True))
+
+
+_RE_PATTERN_ITEMS = re.compile(
+    r"(\**\w+)(.*?)(?:$|(?=\n\**\w+))", flags=re.DOTALL
+)
+
+_STYLE_TO_PADDING = {
+    "numpy": "",
+    "google": " " * 4,
+}
+
+SECTION_NAMES = ("Attributes", "Parameters")
+
+
+def _render(body, style):
+    """Render the items of a section.
+
+    Parameters
+    ----------
+    body: OrderedDict[str, Optional[str]]
+        The items of a section.
+    style: str
+        The doc style.
+
+    Returns
+    -------
+    str
+    """
+    padding = _STYLE_TO_PADDING[style]
+    section = []
+    for key, value in body.items():
+        section += [indent("{}{}".format(key, value), padding)]
+    return "\n".join(section)
+
+
+def set_defaults(doc_sections):
+    """Set the defaults for the sections with items in place.
+
+    Parameters
+    ----------
+    doc_sections: OrderedDict[str, Optional[str]]
+    """
+    for section_name in SECTION_NAMES:
+        doc_sections[section_name] = OrderedDict()
+
+
+def parse(doc_sections):
+    """Parse the sections with items in place.
+
+    Parameters
+    ----------
+    doc_sections: OrderedDict[str, Optional[str]]
+    """
+    for section_name in SECTION_NAMES:
+        section_content = doc_sections[section_name]
+        if section_content:
+            doc_sections[section_name] = OrderedDict(_RE_PATTERN_ITEMS.findall(inspect.cleandoc(section_content)))
+
+
+def merge(prnt_sec, child_sec, merge_within_sections, style):
+    """Merge the doc-sections of the parent's and child's attribute with items.
+
+    Parameters
+    ----------
+    prnt_sec: OrderedDict[str, str]
+    child_sec: OrderedDict[str, str]
+    merge_within_sections: bool
+        Wheter to merge the items.
+    style: str
+        The doc style.
+
+    Returns
+    -------
+    OrderedDict[str, str]
+        The merged items.
+    """
+    if merge_within_sections:
+        body = prnt_sec.copy()
+        body.update(child_sec)
+        body = _render(body, style)
+    else:
+        body = prnt_sec if not child_sec else child_sec
+        body = _render(body, style)
+    return body

tests/metaclass_test.py

@@ -3,8 +3,10 @@
 from types import FunctionType, MethodType
 
 from six import add_metaclass
+import pytest
 
 from custom_inherit import DocInheritMeta
+from custom_inherit._doc_parse_tools.section_items import _RE_PATTERN_ITEMS
 
 try:
     from inspect import signature
@@ -240,6 +242,56 @@ class Child(Mixin, Parent):
     )
 
 
+def test_class_docstring_merge_hierarchy_numpy():
+    @add_metaclass(DocInheritMeta(style="numpy_with_merge"))
+    class GrandParent(object):
+        """GrandParent.
+
+        Attributes
+        ----------
+        foo
+        """
+
+    class Parent(GrandParent):
+        """
+        Attributes
+        ----------
+        bar
+        """
+
+    class Child(Parent):
+        pass
+
+    assert (
+        getdoc(Child)
+        == "GrandParent.\n\nAttributes\n----------\nfoo\nbar"
+    )
+
+
+def test_class_docstring_merge_hierarchy_google():
+    @add_metaclass(DocInheritMeta(style="google_with_merge"))
+    class GrandParent(object):
+        """GrandParent.
+
+        Args:
+            foo
+        """
+
+    class Parent(GrandParent):
+        """
+        Args:
+            bar
+        """
+
+    class Child(Parent):
+        pass
+
+    assert (
+        getdoc(Child)
+        == "GrandParent.\n\nParameters:\n    foo\n    bar"
+    )
+
+
 """ Include special method option"""
 
 @add_metaclass(DocInheritMeta(style=style, include_special_methods=True))
@@ -257,3 +309,17 @@ def test_special_method3():
     # __init__ docstring should inherit from Parent3
     assert isinstance(Kid3().__init__, MethodType)
     assert getdoc(Kid3.__init__) == "valid"
+
+
+@pytest.mark.parametrize(
+    "section_content,expected",
+    (
+        ("foo", [("foo", "")]),
+        ("foo : str\n    Foo.", [("foo", " : str\n    Foo.")]),
+        ("foo\nbar", [("foo", ""), ("bar", "")]),
+        ("foo : str\n    Foo.\nbar", [("foo", " : str\n    Foo."), ("bar", "")]),
+        ("foo : str\n    Foo.\nbar : int\n    Bar.", [("foo", " : str\n    Foo."), ("bar", " : int\n    Bar.")]),
+    )
+)
+def test_regex(section_content, expected):
+    assert _RE_PATTERN_ITEMS.findall(section_content) == expected