Make common STD types known by default

Author: lagru

src/docstub/_analysis.py

@@ -432,11 +432,13 @@ def __init__(
         ----------
         source_pkgs: list[Path], optional
         known_imports: dict[str, KnownImport], optional
+            If not provided, defaults to imports returned by
+            :func:`common_known_imports`.
         """
         if source_pkgs is None:
             source_pkgs = []
         if known_imports is None:
-            known_imports = {}
+            known_imports = common_known_imports()
 
         self.current_source = None
         self.source_pkgs = source_pkgs

src/docstub/_docstrings.py

@@ -12,7 +12,7 @@
 import lark.visitors
 from numpydoc.docscrape import NumpyDocString  # type: ignore[import-untyped]
 
-from ._analysis import KnownImport
+from ._analysis import KnownImport, TypesDatabase
 from ._utils import ContextFormatter, DocstubError, accumulate_qualname, escape_qualname
 
 logger = logging.getLogger(__name__)
@@ -164,11 +164,13 @@ class DoctypeTransformer(lark.visitors.Transformer):
     Examples
     --------
     >>> transformer = DoctypeTransformer()
-    >>> annotation, unknown_names = transformer.doctype_to_annotation("tuple of int")
+    >>> annotation, unknown_names = transformer.doctype_to_annotation(
+    ...     "tuple of (int or ndarray)"
+    ... )
     >>> annotation.value
-    'tuple[int]'
+    'tuple[int | ndarray]'
     >>> unknown_names
-    [('tuple', 0, 5), ('int', 9, 12)]
+    [('ndarray', 17, 24)]
     """
 
     blacklisted_qualnames = frozenset(
@@ -212,15 +214,19 @@ def __init__(self, *, types_db=None, replace_doctypes=None, **kwargs):
         """
         Parameters
         ----------
-        types_db : ~.TypesDatabase
-            A static database of collected types usable as an annotation.
+        types_db : ~.TypesDatabase, optional
+            A static database of collected types usable as an annotation. If
+            not given, defaults to a database with common types from the
+            standard library (see :func:`~.common_known_imports`).
         replace_doctypes : dict[str, str], optional
             Replacements for human-friendly aliases.
         kwargs : dict[Any, Any], optional
             Keyword arguments passed to the init of the parent class.
         """
         if replace_doctypes is None:
             replace_doctypes = {}
+        if types_db is None:
+            types_db = TypesDatabase()
 
         self.types_db = types_db
         self.replace_doctypes = replace_doctypes

tests/test_stubs.py

@@ -139,7 +139,6 @@ def foo(a=None, b=1):
         )
         expected = dedent(
             """
-            from _typeshed import Incomplete as int
             def foo(a: int | None=..., b: int=...) -> None: ...
             """
         )
@@ -252,11 +251,7 @@ def __init__(self, a):
         )
         expected = dedent(
             """
-            from _typeshed import Incomplete as ClassVar
-            from _typeshed import Incomplete as bool
-            from _typeshed import Incomplete as float
-            from _typeshed import Incomplete as int
-            from _typeshed import Incomplete as tuple
+            from typing import ClassVar
             class Foo:
                 a: int
                 b: float
@@ -306,7 +301,6 @@ def foo() -> str:
         )
         expected = dedent(
             """
-            from _typeshed import Incomplete as int
             def foo() -> int: ...
             """
         )