Remove env from autodoc interfaces (#14018)

AA-Turner · web-flow · commit 8c86bad0ef0f · 2025-11-03T00:30:53.000Z
diff --git a/sphinx/ext/autodoc/_generate.py b/sphinx/ext/autodoc/_generate.py
@@ -16,11 +16,11 @@
 from sphinx.util.typing import restify, stringify_annotation
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator
+    from collections.abc import Iterator, Mapping, MutableSet
     from typing import Literal
 
     from sphinx.config import Config
-    from sphinx.environment import BuildEnvironment, _CurrentDocument
+    from sphinx.environment import _CurrentDocument
     from sphinx.events import EventManager
     from sphinx.ext.autodoc._directive_options import _AutoDocumenterOptions
     from sphinx.ext.autodoc._property_types import _ItemProperties
@@ -38,13 +38,14 @@ def _generate_directives(
     *,
     config: Config,
     current_document: _CurrentDocument,
-    env: BuildEnvironment,
     events: EventManager,
     get_attr: _AttrGetter,
     indent: str,
     options: _AutoDocumenterOptions,
     props: _ItemProperties,
     record_dependencies: set[str],
+    ref_context: Mapping[str, str | None],
+    reread_always: MutableSet[str],
     result: StringList,
 ) -> None:
     """Generate reST for the object given by *props*, and possibly for its members.
@@ -136,14 +137,15 @@ def _generate_directives(
         attr_docs=analyzer.attr_docs if analyzer is not None else {},
         config=config,
         current_document=current_document,
-        env=env,
         events=events,
         get_attr=get_attr,
         indent=indent,
         options=options,
         props=props,
         real_modname=real_modname,
         record_dependencies=record_dependencies,
+        ref_context=ref_context,
+        reread_always=reread_always,
         result=result,
     )
 
@@ -204,14 +206,15 @@ def _document_members(
     attr_docs: dict[tuple[str, str], list[str]],
     config: Config,
     current_document: _CurrentDocument,
-    env: BuildEnvironment,
     events: EventManager,
     get_attr: _AttrGetter,
     indent: str,
     options: _AutoDocumenterOptions,
     props: _ItemProperties,
     real_modname: str,
     record_dependencies: set[str],
+    ref_context: Mapping[str, str | None],
+    reread_always: MutableSet[str],
     result: StringList,
 ) -> None:
     """Generate reST for member documentation.
@@ -233,12 +236,13 @@ def _document_members(
         attr_docs=attr_docs,
         config=config,
         current_document=current_document,
-        env=env,
         events=events,
         get_attr=get_attr,
         options=options,
         parent_modname=real_modname,
         props=props,
+        ref_context=ref_context,
+        reread_always=reread_always,
     )
 
     # for implicit module members, check __module__ to avoid
@@ -259,13 +263,14 @@ def _document_members(
             all_members=True,
             config=config,
             current_document=current_document,
-            env=env,
             events=events,
             get_attr=get_attr,
             indent=member_indent,
             options=options,
             props=member_props,
             record_dependencies=record_dependencies,
+            ref_context=ref_context,
+            reread_always=reread_always,
             result=result,
         )
 
diff --git a/sphinx/ext/autodoc/_member_finder.py b/sphinx/ext/autodoc/_member_finder.py
@@ -29,11 +29,11 @@
 from sphinx.util.typing import AnyTypeAliasType
 
 if TYPE_CHECKING:
-    from collections.abc import Iterable, Iterator, Mapping, Sequence, Set
+    from collections.abc import Iterable, Iterator, Mapping, MutableSet, Sequence, Set
     from typing import Any, Literal
 
     from sphinx.config import Config
-    from sphinx.environment import BuildEnvironment, _CurrentDocument
+    from sphinx.environment import _CurrentDocument
     from sphinx.events import EventManager
     from sphinx.ext.autodoc._directive_options import _AutoDocumenterOptions
     from sphinx.ext.autodoc._property_types import _AutodocObjType, _ItemProperties
@@ -96,12 +96,13 @@ def _gather_members(
     attr_docs: dict[tuple[str, str], list[str]],
     config: Config,
     current_document: _CurrentDocument,
-    env: BuildEnvironment,
     events: EventManager,
     get_attr: _AttrGetter,
     options: _AutoDocumenterOptions,
     parent_modname: str,
     props: _ItemProperties,
+    ref_context: Mapping[str, str | None],
+    reread_always: MutableSet[str],
 ) -> list[tuple[_ItemProperties, bool, str]]:
     """Generate reST for member documentation.
 
@@ -179,11 +180,12 @@ def _gather_members(
             type_aliases=config.autodoc_type_aliases,
             current_document=current_document,
             config=config,
-            env=env,
             events=events,
             get_attr=get_attr,
             options=options,
             parent_modname=parent_modname,
+            ref_context=ref_context,
+            reread_always=reread_always,
         )
         if member_props is None:
             continue
diff --git a/sphinx/ext/autodoc/directive.py b/sphinx/ext/autodoc/directive.py
@@ -140,6 +140,8 @@ def run(self) -> list[Node]:
         config = env.config
         current_document = env.current_document
         events = env.events
+        ref_context = env.ref_context
+        reread_always = env.reread_always
 
         props = _load_object_by_name(
             name=name,
@@ -148,10 +150,11 @@ def run(self) -> list[Node]:
             type_aliases=config.autodoc_type_aliases,
             current_document=current_document,
             config=config,
-            env=env,
             events=events,
             get_attr=get_attr,
             options=documenter_options,
+            ref_context=ref_context,
+            reread_always=reread_always,
         )
         if props is None:
             return []
@@ -162,13 +165,14 @@ def run(self) -> list[Node]:
             more_content=self.content,
             config=config,
             current_document=current_document,
-            env=env,
             events=events,
             get_attr=get_attr,
             indent='',
             options=documenter_options,
             props=props,
             record_dependencies=record_dependencies,
+            ref_context=ref_context,
+            reread_always=reread_always,
             result=result,
         )
         if not result:
diff --git a/sphinx/ext/autodoc/importer.py b/sphinx/ext/autodoc/importer.py
@@ -51,12 +51,12 @@
 from sphinx.util.typing import get_type_hints, restify, stringify_annotation
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Mapping, Sequence
+    from collections.abc import Callable, Mapping, MutableSet, Sequence
     from importlib.machinery import ModuleSpec
     from typing import Any, Protocol, TypeAlias
 
     from sphinx.config import Config
-    from sphinx.environment import BuildEnvironment, _CurrentDocument
+    from sphinx.environment import _CurrentDocument
     from sphinx.events import EventManager
     from sphinx.ext.autodoc._directive_options import _AutoDocumenterOptions
     from sphinx.ext.autodoc._property_types import _AutodocFuncProperty, _AutodocObjType
@@ -493,18 +493,19 @@ def _load_object_by_name(
     type_aliases: dict[str, Any] | None,
     current_document: _CurrentDocument,
     config: Config,
-    env: BuildEnvironment,
     events: EventManager,
     get_attr: _AttrGetter,
     options: _AutoDocumenterOptions,
     parent_modname: str | None = None,
+    ref_context: Mapping[str, str | None],
+    reread_always: MutableSet[str],
 ) -> _ItemProperties | None:
     """Import and load the object given by *name*."""
     parsed = _parse_name(
         name=name,
         objtype=objtype,
         current_document=current_document,
-        env=env,
+        ref_context=ref_context,
     )
     if parsed is None:
         return None
@@ -538,7 +539,8 @@ def _load_object_by_name(
             im_ = None
         if im_ is None:
             logger.warning(exc.args[0], type='autodoc', subtype='import_object')
-            env.note_reread()
+            # See BuildEnvironment.note_reread()
+            reread_always.add(current_document.docname)
             return None
         else:
             im = im_
@@ -939,7 +941,7 @@ def _parse_name(
     name: str,
     objtype: _AutodocObjType,
     current_document: _CurrentDocument,
-    env: BuildEnvironment,
+    ref_context: Mapping[str, str | None],
 ) -> tuple[str, tuple[str, ...], str | None, str | None] | None:
     """Parse *name* into module name, path, arguments, and return annotation."""
     # Parse the definition in *name*.
@@ -984,8 +986,8 @@ def _parse_name(
         base=base,
         parents=parents,
         current_document=current_document,
-        ref_context_py_module=env.ref_context.get('py:module'),
-        ref_context_py_class=env.ref_context.get('py:class', ''),
+        ref_context_py_module=ref_context.get('py:module'),
+        ref_context_py_class=ref_context.get('py:class', ''),  # type: ignore[arg-type]
     )
     if resolved is None:
         msg = 'must be implemented in subclasses'
diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py
@@ -307,6 +307,8 @@ def get_items(self, names: list[str]) -> list[tuple[str, str | None, str, str]]:
         events = env.events
         get_attr = _AutodocAttrGetter(env._registry.autodoc_attrgetters)
         opts = _AutoDocumenterOptions()
+        ref_context = env.ref_context
+        reread_always = env.reread_always
 
         max_item_chars = 50
 
@@ -346,10 +348,11 @@ def get_items(self, names: list[str]) -> list[tuple[str, str | None, str, str]]:
                 type_aliases=config.autodoc_type_aliases,
                 current_document=current_document,
                 config=config,
-                env=env,
                 events=events,
                 get_attr=get_attr,
                 options=opts,
+                ref_context=ref_context,
+                reread_always=reread_always,
             )
             if props is None:
                 logger.warning(
diff --git a/tests/test_ext_autodoc/autodoc_util.py b/tests/test_ext_autodoc/autodoc_util.py
@@ -35,32 +35,35 @@ def do_autodoc(
 
     config = app.config
     current_document = app.env.current_document
-    env = app.env
     events = app.events
+    ref_context = app.env.ref_context
+    reread_always: set[str] = set()
     props = _load_object_by_name(
         name=name,
         objtype=obj_type,
         mock_imports=config.autodoc_mock_imports,
         type_aliases=config.autodoc_type_aliases,
         current_document=current_document,
         config=config,
-        env=env,
         events=events,
         get_attr=safe_getattr,
         options=doc_options,
+        ref_context=ref_context,
+        reread_always=reread_always,
     )
     result = StringList()
     if props is not None:
         _generate_directives(
             config=config,
             current_document=current_document,
-            env=env,
             events=events,
             get_attr=safe_getattr,
             indent='',
             options=doc_options,
             props=props,
             record_dependencies=set(),
+            ref_context=ref_context,
+            reread_always=reread_always,
             result=result,
         )
     return result
diff --git a/tests/test_ext_autodoc/test_ext_autodoc.py b/tests/test_ext_autodoc/test_ext_autodoc.py
