Change the typing spec around string references

[davidhalter]

I added this after the discussion here: https://discuss.python.org/t/annotation-string-references-in-class-scope-in-conformance-tests/105439

I'm not 100% sure about the wording, but I hope the direction is fine. I would like to gather some feedback before presenting this to the typing council.

Please also merge #2139 before this pull request. Otherwise it will be very hard to update Zuban's conformance test results in this pull request.

[davidhalter]

@JelleZijlstra Could you please pre-review this? What do you think about this spec change?

[davidhalter]

I think I have integrated all the changes. Is it time to open an issue on the Typing Council’s issue tracker asking for a decision?

[carljm]

One wording nit, one formatting nit, and one conformance suite nit :) But overall this looks great to me.

[rchen152]

Looks good to me - much more consistent and clearly specified than before

[carljm]

This looks good to me. Thanks @davidhalter for getting this clarified.

[davidhalter]

I have integrated all of Carl's suggestions. I will update the conformance tests as soon as the typing council approves this change. If I update it now we probably just run into merge conflicts, since especially pyrefly changes a lot.

@carljm Please let me know if you think something needs more work.

[zzzeek]

Hi, can someone explain the intent of this change to me?

Given, under python 3.14:

Python 3.14.0 (main, Oct 20 2025, 16:44:45) [GCC 14.3.1 20250808 (Red Hat 14.3.1-3)] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> class A: pass
... 
>>> class X:
...     def A(self) -> "A": pass
...     
>>> class Y:
...     def A(self) -> A: pass
...     
>>> typing.get_type_hints(X.A)
{'return': <class '__main__.A'>}
>>> typing.get_type_hints(Y.A)
{'return': <function Y.A at 0x7f2052bc3c10>}
>>> 

does this change propose that it would be impossible for get_type_hints(X.A) to return class A under any circumstances, even with the quotes?

[JelleZijlstra]

Yes

[zzzeek]

are you going to change the behavior of get_type_hints() ? is this a 3.15 change? is there a pep? it should be apparent that this is an enormous backwards-incompatible change I hope?

edit: the pep is pep-749

[zzzeek]

also is this change intended to take place regardless of whether a file is in pep-563 mode or pep-649 mode?

[AlexWaygood]

The non-buggy modern alternative is annotationlib.get_annotations, which is already backported in typing_extensions. I don't think it's workable to change get_type_hints; its questionable behaviour is too deeply embedded

[jorenham]

The non-buggy modern alternative is annotationlib.get_annotations,

Ah perfect; that sounds like a good alternative to typing.get_type_hints that we could reference here instead.

[JelleZijlstra]

Generally the reference should be what happens if you don't stringify the annotation in 3.14+. Annotations are now always lazily evaluated.

[rchen152]

Perfect, thanks. I retried using annotationlib.get_annotations in 3.14 and typing_extensions.get_annotations in 3.12. [1] The matrix came out the same as it did for typing.get_type_hints.

If the intended reference is the non-stringified 3.14 results, then this PR matches the intended runtime behavior in 3.14 onward, which is great.

def int(self) -> int: ... still gives a different result from def int(self) -> "int": ... with get_annotations(eval_str=True); is that intentional? That particular example seems to be the exact case in which the backwards compatibility implications of this change are the most concerning.

[1] using this code, if anyone wants to check my homework ;) I added from __future__ import annotations and eval_str=True to see how stringified annotations evaluate.

from annotationlib import get_annotations

class A:
  str: str

class B:
  x: int
  def int(self): ...
  y: int

class C:
  def int(self) -> int: ...

print(get_annotations(A))
print(get_annotations(B))
print(get_annotations(C.int))

[carljm]

@rchen152 Yes, I think that's a good summary of my suggestion above: to match the runtime behavior of 3.14 exactly, assuming that typing.get_type_hints or annotationlib.get_annotations(eval_str=True) is used to access the annotations and resolve stringified ones. Let's call this proposal "compatible".

The alternative proposal on the table we could call "simple" -- that proposal is that all annotations (including stringified ones) should be resolved the way they would resolve at runtime if they were non-stringified annotations on 3.14+.

To the extent that stringified annotations (mostly) eventually go away, the two proposals will converge, since they differ only in the handling of stringified annotations.

The advantage of "simple" is that there is a single consistent model of name resolution for type checkers to implement. The disadvantages are:

• To be compliant, type checkers have to outright break backwards compatibility for existing code using stringified annotations in these edge cases, as mentioned by some users above.
• Type checkers will resolve stringified annotations in a way that does not match the semantics used by the only tools the stdlib provides to resolve them at runtime. (Thus we can't really claim there is a "single consistent model" for users to understand.)

The "compat" model preserves backwards-compatibility and full consistency with runtime behavior, allowing users to migrate to the new name-resolution semantics on their own schedule (by moving from stringified annotations to non-stringified PEP 647/747 in 3.14+). The cost is more complexity in type checker implementations.

It increasingly seems to me that "compat" is the choice that better serves users of the type system.

(There is a third possible choice, which is to fully embrace the backwards-incompatible change by also changing the runtime behavior of typing.get_type_hints, but I don't see any appetite for that.)

[davidhalter]

What's the consensus here between Carl's simple and compat proposal? I'm personally for "simple", because I don't like the complexity of compat. I'm aware of the runtime issues, but I think most typing users do care about static analysis and not runtime. It seems unexpected that changing Foo[int] to "Foo[int]" would change its meaning.

I would like to move forward with this, because currently it feels like there are 6 competing ways between type checkers how we see forward references and I'm happy to move on with the majority of the council here.

[carljm]

I am happy to move forward with either, if authors of other type checkers are OK with a backwards-incompatible change to their handling of stringified annotation forward references in the ambiguous cases. ty already implements "simple", so that's less work for me :)

[rchen152]

I prefer "simple", although I'd also be okay with "compat". Given the concerns Carl raised, I was going to try implementing it in Pyrefly to make sure I didn't run into any showstopping issues before offering an opinion, but if it's already how ty works, I'm much less worried on that front.

(I'll still implement it in Pyrefly as soon as I can and report back if I run into unanticipated problems, but I don't think we need to wait on that.)

[davidhalter]

I ran the tests with all the type checkers and added notes.

[davidhalter]

@carljm , I think you're the only one who has not ticked off python/typing-council#51.

I guess that there won't be more feedback here, so I feel like if you're ok with this change, we should be able to merge.

[carljm]

Did another review pass on this.

[carljm]

I think we should explicitly specify that the same rules apply to annotations implicitly stringified by from __future__ import annotations. And this should be tested in the conformance suite, too.

[davidhalter]

I added it to the spec. Please review. I will copy the tests/annotations_forward_refs.py to tests/annotations_forward_refs_future.py and add notes once we agree on the rest in this PR.

[carljm]

Sorry, I should have been clearer in my last comment. I do not believe that this is the equivalence we should specify. Part of the point of using from __future__ import annotations is to enable forward references in type annotations, since the annotations are stringified at runtime and won't error. I think the equivalence that we should specify (and test) is that from __future__ import annotations causes all annotations to behave the same way as if they were explicitly stringified, using end-of-scope resolution.

For a pre-3.14 target, this should work with from __future__ import annotations but fail without it:

class C:
    x: B
    
    class B: ...

[davidhalter]

So this would only change the resolution for pre-3.14 targets? I assume that would just mean that the tests marked with # E?: Runtime error prior to 3.14: requires quotes must not be errors I assume?

Sorry for asking for clarification again. My draft for the spec would be:

from __future__ import annotations
----------------------------------

If `from __future__ import annotations` is present in a file, annotations are always resolved at the end of the scope, as they are in Python 3.14 and later.

What do you think?