Implement PEP 649 and PEP 749

[JelleZijlstra]

PEP-649 has been accepted and should be implemented in Python 3.14. Let's use this issue to track the implementation:

• [x] Decide on or clarify the adoption strategy (https://discuss.python.org/t/pep-649-deferred-evaluation-of-annotations-tentatively-accepted/21331/44)
• [x] Add new __annotate__ attributes #119209
• [x] Implement core interpreter changes (e.g., new symbol table functionality) #119361
• [x] Implement new Python-level APIs, like the new format argument to inspect.get_annotations #119891
  • [x] (PEP-649 specifies that inspect.AnnotationsFormat should be a "global enum". Is that desirable? TBD. https://github.com/python/cpython/pull/119361/files#r1614753031)
• [x] Document the new semantics #122235
  • [ ] Add higher-level documentation, e.g. a migration guide away from from __future__ import annotations; an introduction to annotationlib; an update to Larry's annotations HOWTO
• [x] Make staticmethod and classmethod not force evaluation of annotations #119864
• [ ] Adapt standard library code that uses annotations to work excellently with PEP 649
  • [x] dataclasses #119891
  • [x] typing.py: TypedDict, NamedTuple, try to remove dependency on inspect. (If it can't be removed, get rid of the awkward dance we do for typing.Protocol to import inspect.getattr_static lazily.)
  • [x] singledispatch #119891
  • [ ] Also make it only evaluate the relevant parameter, https://github.com/python/cpython/pull/119891#discussion_r1636397226
  • [ ] functools.update_wrapper #119891, #124342
• [x] Add PEP 649-like functionality to TypeAliasType, TypeVar, etc. (pep649-typevar branch in my fork)
• [ ] Make sure the ecosystem is ready by testing third-party libraries like Pydantic
  • [x] typing_extensions: needs changes similar to those in typing.py (python/typing_extensions#412)
  • [ ] beartype: had various unrelated problems on 3.13 (beartype/beartype#387); a few additional tests fail on the PR branch due to direct manipulation of __dict__
  • [ ] typeguard: some unrelated 3.13 problems (agronholm/typeguard#460); no test failures related to PEP 649
  • [ ] pyanalyze: some unrelated 3.13 issues and a few changes necessary due to direct __dict__ access (quora/pyanalyze#773)
  • [ ] pydantic: failed to build for 3.14 so far
• [ ] Optimize the implementation. Ideas:
  • [ ] Avoid creation of function objects and store only code objects instead #124157
  • [x] Avoid creation of AST nodes and use of eval() for ForwardRefs that are just names #124337

Things to revisit:

• [x] Should FORWARDREF be the default? https://github.com/beartype/beartype/pull/440#issuecomment-2373086020
• [ ] Add VALUE_WITH_FAKE_GLOBALS format
• [ ] Name of __annotate__ parameter
• [ ] Should setting __annotations__ invalidate __annotate__?
• [ ] Rename SOURCE to STRING?

I am planning to work on the interpreter core first.

cc @larryhastings @carljm @samuelcolvin

Linked PRs

• gh-119209
• gh-119321
• gh-119361
• gh-119397
• gh-119864
• gh-119891
• gh-120719
• gh-120816
• gh-122074
• gh-122210
• gh-122212
• gh-122235
• gh-122365
• gh-122366
• gh-124326
• gh-124337
• gh-124393
• gh-124415
• gh-124461
• gh-124479
• gh-124561
• gh-124620
• gh-124634
• gh-124730

[Alc-Alc]

PEP-649 has been accepted and should be implemented in PEP 649. Let's use this issue to track the implementation:

Just a clarification / nit, shouldn't the second occurrence of 649 actually be PEP 749?

[JelleZijlstra]

Thanks, I think I meant to say "in Python 3.14". Edited.

[Jens-Dittrich]

Hi everyone,

just wanted to share a (condensed) example where I had to use Forward references outside of type annotations, but in specific parameters of generics as below:

from typing import TypeVar, Generic

BaseClassType = TypeVar("BaseClassType")

class GenericClass(Generic[BaseClassType]):
    def a_method(self) -> BaseClassType:
        pass

class ConcreteClass(GenericClass["ConcreteFriendClass"]):
    pass

GenericClassType = TypeVar("GenericClassType", bound=GenericClass)

class GenericFriendClass(Generic[GenericClassType]):
    def a_method(self) -> GenericClassType:
        pass

class ConcreteFriendClass(GenericFriendClass[ConcreteClass]):
    pass

instance = ConcreteClass()
friend = ConcreteFriendClass()

res = instance.a_method()

Reason is, that ConcreteClass and ConcreteFriendClass are somehow coupled to each other from a business perspective. Not sure, the design is really great or could be improved, but what I want you guys to point you to is the statement of definition of Class ConcreteClass where the friend's class name is specified as forward reference. PyCharm is already able to correctly determine the type of variable res to be of ConcreteFriedClass - so it is at least ForwardReference-ish.

Question now, is this tbh quite corner case also in scope of the ticket, in that case I am glad to contribute above a test case. Just remove the Forward Reference in that line and it shall work. Or is it out of scope, maybe by a flaw of my own understanding or postponed to a later release etc.

EDIT: I just happened to realise that I can retrieve the type parameter at runtime in 3.12 and it turns out to be a Forward Reference

from typing import get_args, ForwardRef
from types import get_original_bases

assert ForwardRef("ConcreteFriendClass") == get_args(get_original_bases(ConcreteClass)[0])[0]

/EDIT

Happy to have a conversation on that.

Regards, Jens

[JelleZijlstra]

@Jens-Dittrich your use case is already solved in Python 3.12, where PEP-695 provides a syntax for generic bounds that is lazily evaluated. If you have further questions, please post on https://discuss.python.org instead so we can keep this issue focused on implementing the Python 3.14 changes.