WIP

Author: lagru

src/docstub-stubs/_docstrings.pyi

@@ -10,7 +10,6 @@ import click
 import lark
 import lark.visitors
 import numpydoc.docscrape as npds
-from _typeshed import Incomplete as Expr
 
 from ._analysis import PyImport, TypeMatcher
 from ._doctype import BlacklistedQualname, Expr, Term, TermKind, parse_doctype

src/docstub-stubs/_doctype.pyi

@@ -7,13 +7,13 @@ from collections.abc import Generator, Iterable, Sequence
 from dataclasses import dataclass
 from pathlib import Path
 from textwrap import indent
-from typing import Any, Final, Literal, Self
+from typing import Any, Final, Self
 
 import lark
 import lark.visitors
 from _typeshed import Incomplete
-from _typeshed import Incomplete as Expression
 
+from ._report import ContextReporter
 from ._utils import DocstubError
 
 logger: Final
@@ -55,7 +55,7 @@ class Expr:
     @property
     def names(self) -> list[Term]: ...
     @property
-    def sub_expressions(self) -> list[Expression] | Literal[1]: ...
+    def sub_expressions(self) -> list[Self]: ...
     def __iter__(self) -> Generator[Expr | Term]: ...
     def format_tree(self) -> str: ...
     def print_tree(self) -> None: ...
@@ -69,9 +69,9 @@ class BlacklistedQualname(DocstubError):
     pass
 
 class DoctypeTransformer(lark.visitors.Transformer):
+    def __init__(self, *, reporter: ContextReporter | None = ...) -> None: ...
     def start(self, tree: lark.Tree) -> Expr: ...
     def qualname(self, tree: lark.Tree) -> Term: ...
-    def qualname(self, tree: lark.Tree) -> Term: ...
     def rst_role(self, tree: lark.Tree) -> Expr: ...
     def ELLIPSES(self, token: lark.Token) -> Term: ...
     def union(self, tree: lark.Tree) -> Expr: ...
@@ -90,6 +90,4 @@ class DoctypeTransformer(lark.visitors.Transformer):
     def extra_info(self, tree: lark.Tree) -> lark.visitors._DiscardType: ...
     def _format_subscription(self, sequence: Sequence[str], *, rule: str) -> Expr: ...
 
-_transformer: Final
-
-def parse_doctype(doctype: str) -> Expr: ...
+def parse_doctype(doctype: str, *, reporter: ContextReporter | None = ...) -> Expr: ...

src/docstub-stubs/_report.pyi

@@ -35,23 +35,43 @@ class ContextReporter:
         short: str,
         *args: Any,
         log_level: int,
-        details: str | None = ...,
+        details: str | tuple[Any, ...] | None = ...,
         **log_kw: Any
     ) -> None: ...
     def debug(
-        self, short: str, *args: Any, details: str | None = ..., **log_kw: Any
+        self,
+        short: str,
+        *args: Any,
+        details: str | tuple[Any, ...] | None = ...,
+        **log_kw: Any
     ) -> None: ...
     def info(
-        self, short: str, *args: Any, details: str | None = ..., **log_kw: Any
+        self,
+        short: str,
+        *args: Any,
+        details: str | tuple[Any, ...] | None = ...,
+        **log_kw: Any
     ) -> None: ...
     def warn(
-        self, short: str, *args: Any, details: str | None = ..., **log_kw: Any
+        self,
+        short: str,
+        *args: Any,
+        details: str | tuple[Any, ...] | None = ...,
+        **log_kw: Any
     ) -> None: ...
     def error(
-        self, short: str, *args: Any, details: str | None = ..., **log_kw: Any
+        self,
+        short: str,
+        *args: Any,
+        details: str | tuple[Any, ...] | None = ...,
+        **log_kw: Any
     ) -> None: ...
     def critical(
-        self, short: str, *args: Any, details: str | None = ..., **log_kw: Any
+        self,
+        short: str,
+        *args: Any,
+        details: str | tuple[Any, ...] | None = ...,
+        **log_kw: Any
     ) -> None: ...
     def __post_init__(self) -> None: ...
     @staticmethod

src/docstub/_docstrings.py

@@ -29,7 +29,7 @@ def _update_qualnames(expr, *, _parents=()):
 
     Parameters
     ----------
-    expr : Expr
+    expr : ~.Expr
     _parents : tuple of (~._doctype.Expr, ...)
 
     Yields
@@ -266,7 +266,7 @@ def doctype_to_annotation(doctype, *, matcher=None, reporter=None, stats=None):
     stats = Stats() if stats is None else stats
 
     try:
-        expression = parse_doctype(doctype)
+        expression = parse_doctype(doctype, reporter=reporter)
         stats.inc_counter("transformed_doctypes")
         reporter.debug(
             "Transformed doctype", details=("   %s\n-> %s", doctype, expression)

src/docstub/_doctype.py

@@ -12,6 +12,7 @@
 import lark
 import lark.visitors
 
+from ._report import ContextReporter
 from ._utils import DocstubError
 
 logger: Final = logging.getLogger(__name__)
@@ -152,7 +153,7 @@ def sub_expressions(self):
 
         Returns
         -------
-        names : list of Expr or {1}
+        names : list of Self
         """
         cls = type(self)
         for child in self.children:
@@ -188,7 +189,7 @@ def format_tree(self):
 
     def print_tree(self):
         """Print full hierarchy as a tree."""
-        print(self.format_tree())
+        print(self.format_tree())  # noqa: T201
 
     def __repr__(self) -> str:
         return f"<{type(self).__name__}: '{self.as_code()}' rule='{self.rule}'>"
@@ -209,40 +210,25 @@ class BlacklistedQualname(DocstubError):
 
 @lark.visitors.v_args(tree=True)
 class DoctypeTransformer(lark.visitors.Transformer):
-    def start(self, tree):
+    def __init__(self, *, reporter=None):
         """
         Parameters
         ----------
-        tree : lark.Tree
-
-        Returns
-        -------
-        out : Expr
+        reporter : ~.ContextReporter
         """
-        return Expr(rule="start", children=tree.children)
+        self.reporter = reporter or ContextReporter(logger=logger)
 
-    def qualname(self, tree):
+    def start(self, tree):
         """
         Parameters
         ----------
         tree : lark.Tree
 
         Returns
         -------
-        out : Term
+        out : Expr
         """
-        children = tree.children
-        _qualname = ".".join(children)
-
-        if _qualname in BLACKLISTED_QUALNAMES:
-            raise BlacklistedQualname(_qualname)
-
-        _qualname = Term(
-            _qualname,
-            kind=TermKind.NAME,
-            pos=(tree.meta.start_pos, tree.meta.end_pos),
-        )
-        return _qualname
+        return Expr(rule="start", children=tree.children)
 
     def qualname(self, tree):
         """
@@ -381,11 +367,11 @@ def natlang_literal(self, tree):
         out = self._format_subscription(items, rule="natlang_literal")
 
         if len(tree.children) == 1:
-            logger.warning(
-                "natural language literal with one item `%s`, "
-                "consider using `%s` to improve readability",
+            details = ("Consider using `%s` to improve readability", "".join(out))
+            self.reporter.warn(
+                "Natural language literal with one item: `{%s}`",
                 tree.children[0],
-                "".join(out),
+                details=details,
             )
         return out
 
@@ -524,16 +510,14 @@ def _format_subscription(self, sequence, *, rule):
         return expr
 
 
-_transformer: Final = DoctypeTransformer()
-
-
-def parse_doctype(doctype):
+def parse_doctype(doctype, *, reporter=None):
     """Turn a type description in a docstring into a type annotation.
 
     Parameters
     ----------
     doctype : str
         The doctype to parse.
+    reporter : ~.ContextReporter, optional
 
     Returns
     -------
@@ -553,5 +537,6 @@ def parse_doctype(doctype):
     <Expr: 'ndarray[float | int]' rule='start'>
     """
     tree = _lark.parse(doctype)
-    expression = _transformer.transform(tree=tree)
+    transformer = DoctypeTransformer(reporter=reporter)
+    expression = transformer.transform(tree=tree)
     return expression

src/docstub/_report.py

@@ -95,7 +95,7 @@ def report(self, short, *args, log_level, details=None, **log_kw):
             Optional formatting arguments for `short`.
         log_level : int
             The logging level.
-        details : str, optional
+        details : str or tuple of (Any, ...), optional
             An optional multiline report with more details.
         **log_kw : Any
         """
@@ -118,7 +118,7 @@ def debug(self, short, *args, details=None, **log_kw):
             A short summarizing report that shouldn't wrap over multiple lines.
         *args : Any
             Optional formatting arguments for `short`.
-        details : str, optional
+        details : str or tuple of (Any, ...), optional
             An optional multiline report with more details.
         **log_kw : Any
         """
@@ -135,7 +135,7 @@ def info(self, short, *args, details=None, **log_kw):
             A short summarizing report that shouldn't wrap over multiple lines.
         *args : Any
             Optional formatting arguments for `short`.
-        details : str, optional
+        details : str or tuple of (Any, ...), optional
             An optional multiline report with more details.
         **log_kw : Any
         """
@@ -152,7 +152,7 @@ def warn(self, short, *args, details=None, **log_kw):
             A short summarizing report that shouldn't wrap over multiple lines.
         *args : Any
             Optional formatting arguments for `short`.
-        details : str, optional
+        details : str or tuple of (Any, ...), optional
             An optional multiline report with more details.
         **log_kw : Any
         """
@@ -169,7 +169,7 @@ def error(self, short, *args, details=None, **log_kw):
             A short summarizing report that shouldn't wrap over multiple lines.
         *args : Any
             Optional formatting arguments for `short`.
-        details : str, optional
+        details : str or tuple of (Any, ...), optional
             An optional multiline report with more details.
         **log_kw : Any
         """
@@ -186,7 +186,7 @@ def critical(self, short, *args, details=None, **log_kw):
             A short summarizing report that shouldn't wrap over multiple lines.
         *args : Any
             Optional formatting arguments for `short`.
-        details : str, optional
+        details : str or tuple of (Any, ...), optional
             An optional multiline report with more details.
         **log_kw : Any
         """

src/docstub/doctype.lark

@@ -78,7 +78,7 @@ literal.1: qualname "[" literal_item ("," literal_item)* "]"
 
 // An single item in a literal expression (or `optional`). We must also allow
 // for qualified names, since a "class" or enum can be used as a literal too.
-literal_item: ELLIPSES | STRING | SIGNED_NUMBER | qualname
+literal_item: STRING | SIGNED_NUMBER | qualname
 
 
 // Natural language forms of the subscription expression for containers.

tests/test_docstrings.py

@@ -5,8 +5,8 @@
 from docstub._analysis import PyImport
 from docstub._docstrings import (
     Annotation,
-    doctype_to_annotation,
     DocstringAnnotations,
+    doctype_to_annotation,
 )
 
 
@@ -37,34 +37,36 @@ def test_unexpected_value(self):
 
 
 class Test_doctype_to_annotation:
-
-    def test_unknown_name(self):
+    def test_unknown_name(self, caplog):
         # Simple unknown name is aliased to typing.Any
         annotation = doctype_to_annotation("a")
         assert annotation.value == "a"
         assert annotation.imports == {
             PyImport(import_="Incomplete", from_="_typeshed", as_="a")
         }
-        assert unknown_names == [("a", 0, 1)]
+        assert caplog.messages == ["Unknown name in doctype: 'a'"]
 
-    def test_unknown_qualname(self):
+    def test_unknown_qualname(self, caplog):
         # Unknown qualified name is escaped and aliased to typing.Any as well
         annotation = doctype_to_annotation("a.b")
         assert annotation.value == "a_b"
         assert annotation.imports == {
             PyImport(import_="Incomplete", from_="_typeshed", as_="a_b")
         }
-        assert unknown_names == [("a.b", 0, 3)]
+        assert caplog.messages == ["Unknown name in doctype: 'a.b'"]
 
-    def test_multiple_unknown_names(self):
+    def test_multiple_unknown_names(self, caplog):
         # Multiple names are aliased to typing.Any
         annotation = doctype_to_annotation("a.b of c")
         assert annotation.value == "a_b[c]"
         assert annotation.imports == {
             PyImport(import_="Incomplete", from_="_typeshed", as_="a_b"),
             PyImport(import_="Incomplete", from_="_typeshed", as_="c"),
         }
-        assert unknown_names == [("a.b", 0, 3), ("c", 7, 8)]
+        assert sorted(caplog.messages) == [
+            "Unknown name in doctype: 'a.b'",
+            "Unknown name in doctype: 'c'",
+        ]
 
 
 class Test_DocstringAnnotations:
@@ -279,4 +281,4 @@ def test_combined_numpydoc_params(self):
         assert annotations.parameters["c"].value == "bool"
 
         assert "d" not in annotations.parameters
-        assert "e" not in annotations.parameters
+        assert "e" not in annotations.parameters