Keep builtin annotations from resolving to project attributes in Sphinx 9 - #74168
Merged
Merged
Conversation
…nx 9 Sphinx 9 falls back from a class lookup to a fuzzy data/attribute search when resolving annotation cross-references. A builtin such as type or object in an annotation then matches every documented attribute with that name, and the docs build fails with "more than one target found" (sphinx-doc/sphinx#14223). Python 3.11 and newer resolve Sphinx 9 from the lock file, so the docs build breaks as soon as it moves off 3.10. Skipping that fallback for builtin names restores the Sphinx 8 behaviour of linking them to the Python documentation. Claude-Session: https://claude.ai/code/session_01SkLWWaTT1cnFqTT1jhFGxe
1 task done
The docs build still type-checks against Sphinx 8 on Python 3.10, where PythonDomain.resolve_xref returns Element | None, while Sphinx 9 narrows it to reference | None. No single precise annotation is a valid override for both. Claude-Session: https://claude.ai/code/session_01SkLWWaTT1cnFqTT1jhFGxe
dabla
approved these changes
Oct 3, 2026
Open
1 task done
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
related: #74151
related: #74167
AI Summary
The docs build runs on the default Python, and
uv.lockresolves Sphinx 8.1.3 on Python 3.10 but Sphinx 9.0.4 on 3.11 (9.1.0 on 3.12+). Moving the default to 3.11 (#74151) therefore moves the docs build to Sphinx 9, and the docs and spellcheck jobs fail.Part of that failure is an upstream regression, sphinx-doc/sphinx#14223: Sphinx 9 added a fallback from a
py:classlookup to a fuzzypy:data/py:attrsearch when resolving annotation cross-references. A builtin such astypeorobjectin an annotation then matches every documented attribute with that name:The new
python_builtin_xrefsextension overrides the Python domain'sresolve_xrefso that a builtin name with no exact match is left unresolved instead of going through that fallback. Intersphinx then links it to the Python docs, which is what Sphinx 8 did. Non-builtin names are untouched. A plainsuppress_warnings = ["ref.python"]would hide the warning but leavetype/objectlinking to an unrelated attribute.The extension is registered in
BASIC_SPHINX_EXTENSIONS(used by the core, provider, chart, ctl and docker-stack docs). Removal is tracked in #74167.The remaining Sphinx 9 warnings are genuine docstring mistakes and are fixed separately in #74169.
Checks run: the new test passes on Sphinx 9.0.4 (Python 3.11) and 8.1.3 (Python 3.10) and fails on 9.0.4 without the extension;
mypy-devel-commonpasses; with both PRs applied,--docs-onlyfor amazon, google, openlineage and task-sdk passes on Python 3.11 / Sphinx 9.0.4, and google spellcheck passes.Was generative AI tooling used to co-author this PR?
Generated-by: Claude Code (Opus 5.5) following the guidelines
🤖 Generated with Claude Code
https://claude.ai/code/session_01SkLWWaTT1cnFqTT1jhFGxe