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?

[zzzeek]

existing libraries which use this pattern will have to use:

>>> _a_cls = A
>>> class Z:
...     def A(self) -> _a_cls: pass
...     
>>> typing.get_type_hints(Z.A)
{'return': <class '__main__.A'>}

[CaselIT]

this would be on top of this breaking change in 3.13 -> 3.14

Python 3.13.9 | packaged by Anaconda, Inc. | (main, Oct 21 2025, 19:09:58) [MSC v.1929 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> class A: pass
...
>>> class F:
...     def A(self)->A: pass
...
>>> import typing
>>> typing.get_type_hints(F.A)
{'return': <class '__main__.A'>}

Python 3.14.3 | packaged by Anaconda, Inc. | (main, Feb 24 2026, 22:45:56) [MSC v.1942 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> class A: pass
...
>>> class F:
...     def A(self) -> A: pass
...
>>> import typing
>>> typing.get_type_hints(F.A)
{'return': <function F.A at 0x0000025520D22610>}

[zzzeek]

I went to where I knew I'd find examples of this, in datetime.pyi, and indeed they are using an alias to work around the ambiguity: https://github.com/python/typeshed/blob/main/stdlib/datetime.pyi#L296

[jorenham]

When reading this at first I was a bit worried that this would cause issues for NumPy, where builtin shadowing (e.g. numpy.bool) and class shadowing (numpy.dtype / numpy.ndarray.dtype) are pretty common things. However, this was recently fixed by @JelleZijlstra in numpy/numpy#31951, so that's no longer an issue.

Anyway, this change reduces ambiguity while improving precision in a directly testable way. The main selling point of string annotations are forward references, so it seems natural for it to shadow "as above, so below". The other explicit "no special casing" vibes I'm getting from this I also really like.

[carljm]

@CaselIT

this would be on top of this breaking change in 3.13 -> 3.14

Not "on top of" - it's the same change. What this PR does is reflect that very same change in runtime semantics of annotations in the specified type checker behavior, so that the two are consistent.

@zzzeek

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

I think this is a really good question, and personally I would be open to specifying a more gradual transition path here, even though it would mean type checkers have to maintain more different behaviors at once.

Specifically, we could say that stringified annotations (whether explicitly strings, or implicitly stringified via from __future__ import annotations) would retain semantics compatible with the runtime behavior of typing.get_type_hints on strings (avoiding the pressure to change that runtime behavior in a backwards-incompatible way), while specifying that all annotations in Python 3.14+ use deferred-evaluation semantics with normal Python scoping rules, just like 3.14+ does at runtime.