Collect imports as scoped types

"from imports" are collected as types within the scope of the containing
module. E.g. "from pathlib import Path" will allow using "Path" inside
the modules scope.

"import" without "from" are collected as scoped type prefixes. Meaning
if a module contains "import scipy as sp", "sp." can be used as a valid
type prefix in that module.

Author: lagru

docs/user_guide.md

@@ -111,8 +111,9 @@ To translate a type from a docstring into a valid type annotation, docstub needs
 Out of the box, docstub will know about builtin types such as `int` or `bool` that don't need an import, and types in `typing`, `collections.abc` from Python's standard library.
 It will source these from the Python environment it is installed in.
 In addition to that, docstub will collect all types in the package directory you are running it on.
+This also includes imported types, which you can then use within the scope of the module that imports them.
 
-However, if you want to use types from third-party libraries you can tell docstub about them in a configuration file.
+However, you can also tell docstub directly about external types in a configuration file.
 Docstub will look for a `pyproject.toml` or `docstub.toml` in the current working directory.
 Or, you can point docstub at TOML file(s) explicitly using the `--config` option.
 In these configuration file(s) you can declare external types directly with
@@ -134,8 +135,9 @@ ski = "skimage"
 
 which will enable any type that is prefixed with `ski.` or `sklearn.tree.`, e.g. `ski.transform.AffineTransform` or `sklearn.tree.DecisionTreeClassifier`.
 
-In both of these cases, docstub doesn't check that these types actually exist.
-Testing the generated stubs with a type checker is recommended.
+> [!IMPORTANT]
+> Docstub doesn't check that types actually exist or if a symbol is a valid type.
+> We always recommend validating the generated stubs with a full type checker!
 
 > [!TIP]
 > Docstub currently collects types statically.

examples/example_pkg-stubs/__init__.pyi

@@ -10,3 +10,6 @@ __all__ = [
 
 class CustomException(Exception):
     pass
+
+class AnotherType:
+    pass

examples/example_pkg-stubs/_basic.pyi

@@ -1,15 +1,16 @@
 # File generated with docstub
 
-import configparser
 import logging
 from collections.abc import Sequence
+from configparser import ConfigParser
+from configparser import ConfigParser as Cfg
 from typing import Any, Literal, Self, Union
 
 from _typeshed import Incomplete
 
-from . import CustomException
+from . import AnotherType, CustomException
 
-logger: Incomplete
+logger: logging.Logger
 
 __all__ = [
     "func_empty",
@@ -39,6 +40,7 @@ def func_use_from_elsewhere(
     a3: ExampleClass.NestedClass,
     a4: ExampleClass.NestedClass,
 ) -> tuple[CustomException, ExampleClass.NestedClass]: ...
+def func_use_from_import(a1: AnotherType, a2: Cfg) -> None: ...
 
 class ExampleClass:
 
@@ -58,6 +60,6 @@ class ExampleClass:
     @some_property.setter
     def some_property(self, value: str) -> None: ...
     @classmethod
-    def method_returning_cls(cls, config: configparser.ConfigParser) -> Self: ...
+    def method_returning_cls(cls, config: ConfigParser) -> Self: ...
     @classmethod
-    def method_returning_cls2(cls, config: configparser.ConfigParser) -> Self: ...
+    def method_returning_cls2(cls, config: ConfigParser) -> Self: ...

examples/example_pkg/__init__.py

@@ -11,3 +11,7 @@
 
 class CustomException(Exception):
     pass
+
+
+class AnotherType:
+    pass

examples/example_pkg/_basic.py

@@ -1,12 +1,19 @@
 """Basic docstring examples.
 
 Docstrings, including module-level ones, are stripped.
+
+Attributes
+----------
+logger : logging.Logger
 """
 
 # Existing imports are preserved
 import logging
+from configparser import ConfigParser as Cfg  # noqa: F401
 from typing import Literal
 
+from . import AnotherType  # noqa: F401
+
 # Assign-statements are preserved
 logger = logging.getLogger(__name__)  # Inline comments are stripped
 
@@ -88,6 +95,16 @@ def func_use_from_elsewhere(a1, a2, a3, a4):
     """
 
 
+def func_use_from_import(a1, a2):
+    """Check using symbols made available in this module with from imports.
+
+    Parameters
+    ----------
+    a1 : AnotherType
+    a2 : Cfg
+    """
+
+
 class ExampleClass:
     """Dummy.
 

pyproject.toml

@@ -119,14 +119,8 @@ run.source = ["docstub"]
 ".*maintenance.*" = "Maintenance"
 
 
-[tool.docstub.types]
-Path = "pathlib"
-
-[tool.docstub.type_prefixes]
-re = "re"
-cst = "libcst"
-lark = "lark"
-numpydoc = "numpydoc"
+[tool.docstub.type_nicknames]
+Path = "pathlib.Path"
 
 
 [tool.mypy]