Improve handling of inline annotations without conflicts (#66)

Make sure that no warning is raised for inline annotations, if there is no
conflicting annotation in a docstring. Otherwise, the inlined annotation 
takes precedence and a warning is printed.

* Don't raise note for inline annotated attributes

when the docstring doesn't contain a type description. In which case
a `FallbackAnnotation` is provided.

Also simplifies the redundant implementation of
`DocstringAnnotations.attributes`.

* Improve tests for doctype-inline conflicts

Author: lagru

src/docstub/_docstrings.py

@@ -677,30 +677,11 @@ def attributes(self):
         -------
         attributes : dict[str, Annotation]
             A dictionary mapping attribute names to their annotations.
-            Attributes without annotations fall back to :class:`_typeshed.Incomplete`.
+            Attributes without annotations fall back to
+            :class:`FallbackAnnotation` which corresponds to
+            :class:`_typeshed.Incomplete`.
         """
-        annotations = {}
-        for attribute in self.np_docstring["Attributes"]:
-            self._handle_missing_whitespace(attribute)
-            if not attribute.type:
-                continue
-
-            ds_line = 0
-            for i, line in enumerate(self.docstring.split("\n")):
-                if attribute.name in line and attribute.type in line:
-                    ds_line = i
-                    break
-
-            if attribute.name in annotations:
-                self.reporter.message(
-                    "duplicate attribute name in docstring",
-                    details=self.reporter.underline(attribute.name),
-                )
-                continue
-
-            annotation = self._doctype_to_annotation(attribute.type, ds_line=ds_line)
-            annotations[attribute.name.strip()] = annotation
-
+        annotations = self._section_annotations("Attributes")
         return annotations
 
     @cached_property
@@ -711,7 +692,9 @@ def parameters(self):
         -------
         parameters : dict[str, Annotation]
             A dictionary mapping parameters names to their annotations.
-            Parameters without annotations fall back to :class:`_typeshed.Incomplete`.
+            Parameters without annotations fall back to
+            :class:`FallbackAnnotation` which corresponds to
+            :class:`_typeshed.Incomplete`.
         """
         param_section = self._section_annotations("Parameters")
         other_section = self._section_annotations("Other Parameters")

src/docstub/_stubs.py

@@ -15,7 +15,7 @@
 import libcst.matchers as cstm
 
 from ._analysis import PyImport
-from ._docstrings import DocstringAnnotations, DoctypeTransformer
+from ._docstrings import DocstringAnnotations, DoctypeTransformer, FallbackAnnotation
 from ._utils import ErrorReporter, module_name_from_path
 
 logger = logging.getLogger(__name__)
@@ -701,7 +701,7 @@ def leave_AnnAssign(self, original_node, updated_node):
                     updated_node.annotation, annotation=expr
                 )
 
-            else:
+            elif pytype != FallbackAnnotation:
                 # Notify about ignored docstring annotation
                 # TODO: either remove message or print only in verbose mode
                 position = self.get_metadata(

tests/test_stubs.py

@@ -313,13 +313,13 @@ def test_keep_assign_param(self):
         result = transformer.python_to_stub(source)
         assert expected == result
 
-    def test_keep_inline_assign_with_doctype(self, capsys):
+    def test_module_assign_conflict(self, capsys):
         source = dedent(
             '''
             """
             Attributes
             ----------
-            a : Sized
+            a : int
             """
             a: str
             '''
@@ -334,9 +334,43 @@ def test_keep_inline_assign_with_doctype(self, capsys):
         assert expected == result
 
         captured = capsys.readouterr()
-        assert "Keeping existing inline annotation for assignment" in captured.out
+        assert captured.out == (
+            "Keeping existing inline annotation for assignment\n"
+            "    str\n"
+            "    ^^^ ignoring docstring: int\n"
+            "\n"
+        )
 
-    def test_keep_class_assign_param(self):
+    def test_module_assign_no_conflict(self, capsys):
+        source = dedent(
+            '''
+            """
+            Attributes
+            ----------
+            a :
+                No type info here; it's already inlined.
+            b : float
+            """
+            a: int
+            b = 3
+            '''
+        )
+        expected = dedent(
+            """
+            a: int
+            b: float
+            """
+        )
+        transformer = Py2StubTransformer()
+        result = transformer.python_to_stub(source)
+        assert expected == result
+
+        # No warning should have been raised, since there is no conflict
+        # between docstring and inline annotation
+        output = capsys.readouterr()
+        assert output.out == ""
+
+    def test_class_assign_keep_inline_annotation(self):
         source = dedent(
             """
             class Foo:
@@ -353,7 +387,7 @@ class Foo:
         result = transformer.python_to_stub(source)
         assert expected == result
 
-    def test_keep_inline_class_assign_with_doctype(self, capsys):
+    def test_class_assign_conflict(self, capsys):
         source = dedent(
             '''
             class Foo:
@@ -376,9 +410,45 @@ class Foo:
         assert expected == result
 
         captured = capsys.readouterr()
-        assert "Keeping existing inline annotation for assignment" in captured.out
+        assert captured.out == (
+            "Keeping existing inline annotation for assignment\n"
+            "    str\n"
+            "    ^^^ ignoring docstring: Sized\n"
+            "\n"
+        )
 
-    def test_keep_inline_param(self):
+    def test_class_assign_no_conflict(self, capsys):
+        source = dedent(
+            '''
+            class Foo:
+                """
+                Attributes
+                ----------
+                a :
+                    No type info here; it's already inlined.
+                b : float
+                """
+                a: int
+                b = 3
+            '''
+        )
+        expected = dedent(
+            """
+            class Foo:
+                a: int
+                b: float
+            """
+        )
+        transformer = Py2StubTransformer()
+        result = transformer.python_to_stub(source)
+        assert expected == result
+
+        # No warning should have been raised, since there is no conflict
+        # between docstring and inline annotation
+        output = capsys.readouterr()
+        assert output.out == ""
+
+    def test_param_keep_inline_annotation(self):
         source = dedent(
             """
             def foo(a: str) -> None:
@@ -394,7 +464,7 @@ def foo(a: str) -> None: ...
         result = transformer.python_to_stub(source)
         assert expected == result
 
-    def test_keep_inline_param_with_doctype(self, capsys):
+    def test_param_conflict(self, capsys):
         source = dedent(
             '''
             def foo(a: int) -> None:
@@ -416,9 +486,14 @@ def foo(a: int) -> None: ...
         assert expected == result
 
         captured = capsys.readouterr()
-        assert "Keeping existing inline parameter annotation" in captured.out
+        assert captured.out == (
+            "Keeping existing inline parameter annotation\n"
+            "    int\n"
+            "    ^^^ ignoring docstring: Sized\n"
+            "\n"
+        )
 
-    def test_keep_inline_return(self):
+    def test_return_keep_inline_annotation(self):
         source = dedent(
             """
             def foo() -> str:
@@ -434,7 +509,7 @@ def foo() -> str: ...
         result = transformer.python_to_stub(source)
         assert expected == result
 
-    def test_keep_inline_return_with_doctype(self, capsys):
+    def test_return_conflict(self, capsys):
         source = dedent(
             '''
             def foo() -> int:
@@ -456,7 +531,12 @@ def foo() -> int: ...
         assert expected == result
 
         captured = capsys.readouterr()
-        assert "Keeping existing inline return annotation" in captured.out
+        assert captured.out == (
+            "Keeping existing inline return annotation\n"
+            "    int\n"
+            "    ^^^ ignoring docstring: Sized\n"
+            "\n"
+        )
 
     def test_preserved_type_comment(self):
         source = dedent(