🐛 fix(resolver): accept guarded code the interpreter rejects

A TYPE_CHECKING block is read by type checkers, not run by the interpreter,
so it holds constructs that raise when executed. xarray writes
TypeVar("T_XarrayOther", bound="DataArray" | Dataset), which is a TypeError
at runtime. Executing the guard to recover its names hit that error, warned
about a failed type import, and then warned a second time when the
annotation using the name could not resolve. Both warnings pointed at code
that is correct.

An import that fails still warns, since a missing dependency is worth
knowing about. Any other statement now stands its names in as forward
references, which is what a type checker sees and what the renderer already
knows how to print.

Closes #751

Author: gaborbernat

pyproject.toml

@@ -131,6 +131,9 @@ lint.per-file-ignores."tests/roots/test-integration/mod_forward_ref.py" = [
   "I002",    # intentionally omits `from __future__ import annotations` to test forward references
   "PLR6301", # method must be instance method to test class forward refs
 ]
+lint.per-file-ignores."tests/roots/test-unexecutable-guard/demo_unexecutable_guard.py" = [
+  "UP047", # the legacy TypeVar spelling is what the guard cannot execute
+]
 lint.per-file-ignores."tests/roots/test-pyi-stubs/stub_mod.py" = [
   "ANN",     # intentionally has no type annotations to simulate a C extension
   "I002",    # intentionally omits `from __future__ import annotations`

src/sphinx_autodoc_typehints/_resolver/_type_hints.py

@@ -201,15 +201,18 @@ def _execute_guarded_code(autodoc_mock_imports: list[str], obj: Any, module_code
     for _, part in _TYPE_GUARD_IMPORT_RE.findall(module_code):
         try:
             # One statement at a time, so an unimportable optional dependency cannot strand the names after it — #741
-            statements = [ast.unparse(node) for node in ast.parse(textwrap.dedent(part)).body]
+            statements = ast.parse(textwrap.dedent(part)).body
         except SyntaxError as exc:
             _warn_guarded_import(obj, exc)
             continue
         for statement in statements:
             try:
-                _run_guarded_import(autodoc_mock_imports, obj, statement)
+                _run_guarded_import(autodoc_mock_imports, obj, ast.unparse(statement))
             except Exception as exc:  # ruff:ignore[blind-except]
-                _warn_guarded_import(obj, exc)
+                if isinstance(statement, ast.Import | ast.ImportFrom):
+                    _warn_guarded_import(obj, exc)
+                else:
+                    _bind_unresolvable_names(obj, statement)
 
 
 def _warn_guarded_import(obj: Any, exc: Exception) -> None:
@@ -223,6 +226,21 @@ def _warn_guarded_import(obj: Any, exc: Exception) -> None:
     )
 
 
+def _bind_unresolvable_names(obj: Any, statement: ast.stmt) -> None:
+    """
+    Bind the names a guarded statement would have defined, so annotations can still use them.
+
+    Type checkers accept constructs the interpreter rejects, e.g. ``TypeVar("T", bound="A" | B)`` (#751).
+    """
+    if isinstance(statement, ast.ClassDef | ast.FunctionDef | ast.AsyncFunctionDef):
+        names = [statement.name]
+    else:
+        names = [n.id for n in ast.walk(statement) if isinstance(n, ast.Name) and isinstance(n.ctx, ast.Store)]
+    namespace = getattr(obj, "__globals__", obj.__dict__)
+    for name in names:
+        namespace.setdefault(name, MyTypeAliasForwardRef(name))
+
+
 def _run_guarded_import(autodoc_mock_imports: list[str], obj: Any, guarded_code: str) -> None:
     ns = getattr(obj, "__globals__", obj.__dict__)
     try:

tests/roots/test-unexecutable-guard/conf.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+import pathlib
+import sys
+
+master_doc = "index"
+sys.path.insert(0, str(pathlib.Path(__file__).parent))
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx_autodoc_typehints",
+]

tests/roots/test-unexecutable-guard/demo_unexecutable_guard.py

@@ -0,0 +1,41 @@
+"""Module demonstrating type guarded code that the interpreter cannot run."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, TypeVar
+
+if TYPE_CHECKING:
+    from demo_unexecutable_guard_dummy import Dataset
+
+    T_Other = TypeVar("T_Other", bound="DataArray" | Dataset)
+
+    class Wrapper(Dataset[int]):
+        """A wrapped dataset."""
+
+
+class DataArray:
+    """An array."""
+
+
+def combine(array: DataArray, other: T_Other) -> T_Other:
+    """
+    Combine two arrays.
+
+    :param array: the first array
+    :param other: the second array
+    :return: the combination
+    """
+    raise NotImplementedError
+
+
+def wrap(array: DataArray) -> Wrapper:
+    """
+    Wrap an array.
+
+    :param array: the array to wrap
+    :return: the wrapper
+    """
+    raise NotImplementedError
+
+
+__all__ = ["DataArray", "combine", "wrap"]

tests/roots/test-unexecutable-guard/demo_unexecutable_guard_dummy.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+
+class Dataset:
+    """Generic to a type checker only, so subscripting it raises."""

tests/roots/test-unexecutable-guard/index.rst

@@ -0,0 +1,2 @@
+.. automodule:: demo_unexecutable_guard
+   :members:

tests/test_guarded_import.py

@@ -57,3 +57,48 @@ def func(x: int) -> int:
     app.build()
     assert "build succeeded" in status.getvalue()
     assert "Failed guarded type import" not in warning.getvalue()
+
+
+@pytest.mark.sphinx("text", testroot="unexecutable-guard")
+def test_guarded_code_the_interpreter_rejects(app: SphinxTestApp, status: StringIO, warning: StringIO) -> None:
+    """Names from type-checker-only code render without warnings (#751)."""
+    app.build()
+    assert "build succeeded" in status.getvalue()
+    assert not warning.getvalue()
+    text = (Path(app.srcdir) / "_build" / "text" / "index.txt").read_text()
+    assert text == dedent("""\
+        Module demonstrating type guarded code that the interpreter cannot
+        run.
+
+        class demo_unexecutable_guard.DataArray
+
+           An array.
+
+        demo_unexecutable_guard.combine(array, other)
+
+           Combine two arrays.
+
+           Parameters:
+              * **array** ("DataArray") -- the first array
+
+              * **other** (T_Other) -- the second array
+
+           Return type:
+              T_Other
+
+           Returns:
+              the combination
+
+        demo_unexecutable_guard.wrap(array)
+
+           Wrap an array.
+
+           Parameters:
+              **array** ("DataArray") -- the array to wrap
+
+           Return type:
+              Wrapper
+
+           Returns:
+              the wrapper
+        """)