WIP

Author: lagru

src/docstub-stubs/_docstrings.pyi

@@ -12,16 +12,15 @@ import lark.visitors
 import numpydoc.docscrape as npds
 
 from ._analysis import PyImport, TypeMatcher
-from ._doctype import BlacklistedQualname, Expression, Token, TokenKind, parse_doctype
+from ._doctype import BlacklistedQualname, Expr, Term, TermKind, parse_doctype
 from ._report import ContextReporter, Stats
 from ._utils import escape_qualname
 
 logger: logging.Logger
 
-def update_qualnames(
-    expr: Expression, *, _parents: tuple[Expression, ...] = ...
-) -> Generator[tuple[tuple[Expression, ...], Token], str]: ...
-def _find_one_token(tree: lark.Tree, *, name: str) -> lark.Token: ...
+def _update_qualnames(
+    expr: Expr, *, _parents: tuple[Expr, ...] = ...
+) -> Generator[tuple[tuple[Expr, ...], Term], str]: ...
 @dataclass(frozen=True, slots=True, kw_only=True)
 class Annotation:
 
@@ -52,6 +51,13 @@ def _uncombine_numpydoc_params(
     params: list[npds.Parameter],
 ) -> Generator[npds.Parameter]: ...
 def _red_partial_underline(doctype: str, *, start: int, stop: int) -> str: ...
+def doctype_to_annotation(
+    doctype: str,
+    *,
+    matcher: TypeMatcher | None = ...,
+    reporter: ContextReporter | None = ...,
+    stats: Stats | None = ...,
+) -> Annotation: ...
 
 class DocstringAnnotations:
     docstring: str
@@ -62,13 +68,10 @@ class DocstringAnnotations:
         self,
         docstring: str,
         *,
-        matcher: TypeMatcher,
+        matcher: TypeMatcher | None = ...,
         reporter: ContextReporter | None = ...,
         stats: Stats | None = ...,
     ) -> None: ...
-    def _doctype_to_annotation(
-        self, doctype: str, ds_line: int = ...
-    ) -> Annotation: ...
     @cached_property
     def attributes(self) -> dict[str, Annotation]: ...
     @cached_property

src/docstub-stubs/_doctype.pyi

@@ -0,0 +1,88 @@
+# File generated with docstub
+
+import enum
+import keyword
+import logging
+from collections.abc import Generator, Iterable, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from textwrap import indent
+from typing import Any, Final
+
+import lark
+import lark.visitors
+from _typeshed import Incomplete
+
+from ._utils import DocstubError
+
+logger: Final
+
+grammar_path: Final
+
+with grammar_path.open() as file:
+    _grammar: Final
+
+_lark: Final
+
+def flatten_recursive(iterable: Iterable[Iterable | str]) -> Generator[str]: ...
+def insert_between(iterable: Iterable, *, sep: Any) -> list[Any]: ...
+
+class TermKind(enum.StrEnum):
+
+    NAME = enum.auto()
+    LITERAL = enum.auto()
+    SYNTAX = enum.auto()
+
+class Term(str):
+
+    __slots__: Final
+
+    def __new__(
+        cls, value: str, *, kind: TermKind | str, pos: tuple[int, int] | None = ...
+    ) -> None: ...
+    def __repr__(self) -> str: ...
+    def __getnewargs_ex__(self) -> tuple[tuple[Any, ...], dict[str, Any]]: ...
+
+@dataclass(slots=True)
+class Expr:
+
+    rule: str
+    children: list[Expr | Term]
+
+    @property
+    def terms(self) -> list[Term]: ...
+    @property
+    def names(self) -> list[Term]: ...
+    def __iter__(self) -> Generator[Expr | Term]: ...
+    def format_tree(self) -> str: ...
+    def __repr__(self) -> str: ...
+    def __str__(self) -> str: ...
+    def as_code(self) -> str: ...
+
+BLACKLISTED_QUALNAMES: Final
+
+class BlacklistedQualname(DocstubError):
+    pass
+
+class DoctypeTransformer(lark.visitors.Transformer):
+    def start(self, tree: lark.Tree) -> Expr: ...
+    def qualname(self, tree: lark.Tree) -> Term: ...
+    def ELLIPSES(self, token: lark.Token) -> Term: ...
+    def union(self, tree: lark.Tree) -> Expr: ...
+    def subscription(self, tree: lark.Tree) -> Expr: ...
+    def natlang_literal(self, tree: lark.Tree) -> Expr: ...
+    def literal_item(self, tree: lark.Tree) -> Term: ...
+    def natlang_container(self, tree: lark.Tree) -> Expr: ...
+    def natlang_array(self, tree: lark.Tree) -> Expr: ...
+    def array_name(self, tree: lark.Tree) -> Term: ...
+    def dtype(self, tree: lark.Tree) -> Expr: ...
+    def shape(self, tree: lark.Tree) -> lark.visitors._DiscardType: ...
+    def optional_info(self, tree: lark.Tree) -> lark.visitors._DiscardType: ...
+    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: ...