Do not warn on references to in-scope PEP 695 type parameters - #14518
Open
apoorvdarshan wants to merge 1 commit into
Open
Do not warn on references to in-scope PEP 695 type parameters#14518apoorvdarshan wants to merge 1 commit into
apoorvdarshan wants to merge 1 commit into
Conversation
References to PEP 695 type parameters in type parameter bounds, argument lists, return annotations, and the bodies of generic objects were turned into py:class cross references. Since type parameters have no link target and shadow any documented object of the same name, this produced spurious 'reference target not found' warnings in nitpicky mode (one reporter counted about a thousand in an 8k LoC project). Track the type parameter names introduced by a signature in env.ref_context while the signature and the object's content are parsed, and render in-scope names as plain text instead of pending cross references. The rendered output is unchanged (an unresolvable reference already fell back to plain text); out-of-scope references still warn. Fixes sphinx-doc#14462
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
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.
Fixes #14462
Problem
References to PEP 695 type parameters — in type parameter bounds, argument lists, return annotations, and the bodies of generic classes — are converted into
py:classpending cross-references. Type parameters have no link target and, per PEP 695 scoping, shadow any documented object of the same name, so every such reference produces a spuriousreference target not foundwarning under-n(the reporter counts ~1000 in an 8k LoC project). Reproduced onmasterwith the issue's snippet (3 spurious warnings).Fix
PyObject.handle_signature()records the type parameter names introduced by a signature inenv.ref_context['py:type_params'](saving the enclosing scope on the directive instance), so they are visible while parsing the type parameter list itself (bounds/constraints/defaults), the argument list, and the return annotation.PyObject.after_content()restores the enclosing scope, so the names also cover the object's body — e.g.py:method:: eggs(arg: int) -> Tinsidepy:class:: Spam[T]— and never leak past the directive (mirrors the existingpy:class/py:moduleref-context handling, including nesting).type_to_xref()renders an in-scope, un-dotted name as plainTextinstead of apending_xref. Rendered output is unchanged — an unresolvable reference already fell back to plain text — but no warning is emitted, and a documented class shadowed by a type parameter is no longer (incorrectly) linked.Out-of-scope references still warn:
py:function:: outside(x: T)after a generic class continues to reportT.Two existing doctree-shape tests (
test_class_def_pep_695,test_class_def_pep_696) pinned the old behavior of in-scope names inside bounds/constraints (e.g.S: Sequence[T]) being pending xrefs; they were updated to expect plain text for exactly those names (Sequence,tuple,intetc. remain xrefs).This is complementary to #14504, which handles the autodoc/runtime-
TypeVarside viamissing-reference; this PR covers the directive-syntax layer, where scope is known at parse time.Verification
test-domain-py-type-param-scope+test_pep_695_type_param_scope_nitpicky(asserts the only remaining warning is the genuinely out-of-scopeT) andtest_pep_695_type_params_render_as_text— both fail onmaster.test_intl): ~2,900 passed, failure set byte-identical tomasterin my environment (6 pre-existing environment-dependent failures).ruff check/ruff formatclean on changed files;mypyclean on both changed modules.AI policy disclosure
Per the AI policy: this contribution was prepared with the assistance of an AI tool (Claude Code), used for the investigation, the patch, and the tests. I reproduced the issue, reviewed and verified the change and all test results, and take responsibility for the contribution — I'll respond to review feedback personally.