PEP about implementing PEP 649

[JelleZijlstra]

I am planning to write a PEP focused on how to implement and ship PEP 649. This PEP will include some changes and additions to the behavior specified in PEP 649 itself.

Topics to cover:

• Transition plan: what happens to from __future__ import annotations? (Current leaning: keep it around until 3.13 reaches EOL, then deprecate it and remove it two years later.)
• REPL behavior change (https://discuss.python.org/t/pep-649-behavior-of-the-repl/54109)
• New annotations module (https://discuss.python.org/t/pep-649-deferred-evaluation-of-annotations-tentatively-accepted/21331/69)
• Enum for annotation format? (gh-119180: PEP 649 compiler changes python/cpython#119361 (comment))
• Revisit "set __annotate__ to None"? (gh-119180: PEP 649: Add __annotate__ attributes python/cpython#119209 (review))
• Remove the suggested flag on code objects to mark if they can be evaluated with the special execution environment?
• Specify behavior for annotations on classmethod and staticmethod
• Add typing.evaluate_forward_ref? Combines evaluating the ForwardRef with typing-specific conversions (typing._type_check).
• Specify mechanism for FORWARDREF/SOURCE evaluation of TypeVar bounds etc.

cc @carljm @AlexWaygood

I'm going to hold off on writing the PEP until someone adds PEP 748, so I can get PEP 749 :)

[JelleZijlstra]

Draft text: https://github.com/JelleZijlstra/peps/blob/pep749/peps/pep-0749.rst

[AlexWaygood]

Great idea. Made a PR at #12 suggesting a few small improvements. Some more miscellaneous comments:

• In the section title "The future of from __future__ import annotations, it might be good to explicitly address Inada Naoki's concern that PEP-649 will be less performant and memory-efficient than PEP-563 for applications that do not care about annotations being accurately introspected. He's made this point several times in various forums, so I think it's clear he feels strongly about it. He's concerned in particular about the implications for the number of GC-tracked objects under PEP 649 (https://discuss.python.org/t/a-massive-pep-649-update-with-some-major-course-corrections/25672/33, and https://discuss.python.org/t/lazy-imports-and-pep-649/48548/7, etc.). I agree with you that having consistent semantics for Python annotations outweighs these concerns, and these performance/memory concerns are somewhat hypothetical right now (I think) -- but I think we should tackle the concerns directly nonetheless.
• Name of the new "annotation tools" module: I'm not a massive fan of calling it annotations, as I think there's too much potential for confusing it with __future__.annotations. I kinda like the name annotools that Erlend suggested, but you may be right that it's not the most obvious name for people who don't spend a significant amount of their spare time thinking about the standard library 🙃
• This paragraph could possibly do with an example of exactly what this proposed change would mean for users of the REPL:

  peps/peps/pep-0749.rst

  Lines 200 to 203 in b08a9c3

  	Because the REPL is evaluated line by line, we would generate a new ``__annotate__``
  	function for every evaluated line that contains annotations. Whenever a line
  	containing annotations is evaluated, the previous ``__annotate__`` function is
  	lost.

[carljm]

The PEP looks great, thank you for writing it up! A few thoughts:

• The line about dataclasses.dataclass eagerly evaluating annotations is potentially confusing, since I think it's pretty important that in the same Python version we land 649, we also change dataclasses.dataclass to use FORWARDREFS mode and avoid this problem. I don't want to wrongly give the impression that we won't do this, and dataclasses.dataclass will actually prevent forward references in annotations under 649 semantics. I think this point is actually fine without the parenthetical and the example of dataclass?
• Regarding the new annotations/annotools module: I agree with the comment you make in the rejected alternatives section about keeping a separation between typing module and annotations utilities. But probably the biggest chunk of Python code added in 649 will be the Stringizer stuff for supporting FORWARDREFS and SOURCE modes. 649 specifies that this will just be added to the existing typing.ForwardRef class. The annotations module will then need to import and use typing.ForwardRef. Is this really the preferred dependency direction? It seems to me that it might be better to move ForwardRef into the new annotations/annotools module and have typing import it from there?
• I really don't like the idea of starting with _annotations initially. I think we can say with high confidence that the result will be that lots of people will import and use things from the _annotations module anyway, and then we will feel pressure to maintain backward compatibility of it even though it was technically not public. Does this really gain us anything? I would be inclined not to even include this option, or if we include it, present this downside as well.
• I think the Specification section under REPL behavior should probably mention how this affects __annotations__ as well, not only __annotate__.
• There's an empty Specification section with the placeholder contents.

[JelleZijlstra]

Thank you both for the comments!

• In the section title "The future of from __future__ import annotations, it might be good to explicitly address Inada Naoki's concern that PEP-649 will be less performant and memory-efficient than PEP-563 for applications that do not care about annotations being accurately introspected. He's made this point several times in various forums, so I think it's clear he feels strongly about it. He's concerned in particular about the implications for the number of GC-tracked objects under PEP 649 (https://discuss.python.org/t/a-massive-pep-649-update-with-some-major-course-corrections/25672/33, and https://discuss.python.org/t/lazy-imports-and-pep-649/48548/7, etc.). I agree with you that having consistent semantics for Python annotations outweighs these concerns, and these performance/memory concerns are somewhat hypothetical right now (I think) -- but I think we should tackle the concerns directly nonetheless.

I'm not sure this is appropriate for the PEP, except perhaps if we get some real performance data for the implementation. PEP 649 was accepted and it shouldn't be a goal to relitigate the concerns that were brought up when it was being discussed; instead this new PEP should focus on concrete places where the details of PEP 649 don't work out well.

• Name of the new "annotation tools" module: I'm not a massive fan of calling it annotations, as I think there's too much potential for confusing it with __future__.annotations. I kinda like the name annotools that Erlend suggested, but you may be right that it's not the most obvious name for people who don't spend a significant amount of their spare time thinking about the standard library 🙃

Added this as an argument. I don't really have strong opinions on the name.

• This paragraph could possibly do with an example of exactly what this proposed change would mean for users of the REPL:

  peps/peps/pep-0749.rst

  Lines 200 to 203 in b08a9c3

  	Because the REPL is evaluated line by line, we would generate a new ``__annotate__``
  	function for every evaluated line that contains annotations. Whenever a line
  	containing annotations is evaluated, the previous ``__annotate__`` function is
  	lost.

Added an example.

• The line about dataclasses.dataclass eagerly evaluating annotations is potentially confusing, since I think it's pretty important that in the same Python version we land 649, we also change dataclasses.dataclass to use FORWARDREFS mode and avoid this problem. I don't want to wrongly give the impression that we won't do this, and dataclasses.dataclass will actually prevent forward references in annotations under 649 semantics. I think this point is actually fine without the parenthetical and the example of dataclass?

I felt that a concrete example would be helpful and I tried to emphasize that we're talking about the 3.13 version of dataclasses, since we'll definitely fix the 3.14 version. However, it's apparently still confusing, so I'll look into rewording.

• Regarding the new annotations/annotools module: I agree with the comment you make in the rejected alternatives section about keeping a separation between typing module and annotations utilities. But probably the biggest chunk of Python code added in 649 will be the Stringizer stuff for supporting FORWARDREFS and SOURCE modes. 649 specifies that this will just be added to the existing typing.ForwardRef class. The annotations module will then need to import and use typing.ForwardRef. Is this really the preferred dependency direction? It seems to me that it might be better to move ForwardRef into the new annotations/annotools module and have typing import it from there?

Yes, something has to change there. Maybe typing.ForwardRef can become an alias for annotations.ForwardRef, though that also causes issues because the implementation of ForwardRef is intertwined with the rest of typing. Or maybe we can simply have a separate annotations.ForwardRef. I'll have to write more about this after I work on the implementation of the annotations module.

• I really don't like the idea of starting with _annotations initially. I think we can say with high confidence that the result will be that lots of people will import and use things from the _annotations module anyway, and then we will feel pressure to maintain backward compatibility of it even though it was technically not public. Does this really gain us anything? I would be inclined not to even include this option, or if we include it, present this downside as well.

I anticipate that the Steering Council will have concerns about adding a new module straight to the standard library (remember there was a talk about having PEPs incubate outside of the stdlib if possible), so I think it's important to address such concerns immediately. But agree that people would likely start using it even if we make it private, so I can add something to that effect.

• I think the Specification section under REPL behavior should probably mention how this affects __annotations__ as well, not only __annotate__.

Good point, will do.

• There's an empty Specification section with the placeholder contents.

Yes, there are a few empty sections; will remove them later.

[carljm]

I anticipate that the Steering Council will have concerns about adding a new module straight to the standard library (remember there was a talk about having PEPs incubate outside of the stdlib if possible), so I think it's important to address such concerns immediately. But agree that people would likely start using it even if we make it private, so I can add something to that effect.

Yes, I think it's definitely good that you address this in general. IMO the most important factor here is simply that the stdlib itself needs it. And given that, I'm not sure that "in the stdlib, but with a leading underscore" is a compelling option that practically meets the goals of "develop outside the stdlib."

[AlexWaygood]

I'm not sure this is appropriate for the PEP, except perhaps if we get some real performance data for the implementation. PEP 649 was accepted and it shouldn't be a goal to relitigate the concerns that were brought up when it was being discussed; instead this new PEP should focus on concrete places where the details of PEP 649 don't work out well.

Fair enough! To be clear: I mention this not because I think it's important to justify PEP 649 over PEP 563 in the PEP, but because the PEP seeks to answer the question of how and when we should deprecate PEP 563. I think it's a significant argument some have raised to argue that we should never deprecate PEP 563 (or that we should at least wait until doing so), and should instead allow the two possible modes to coexist indefinitely. I'm not suggesting we discuss these arguments in depth, but I think a brief acknowledgement and/or a link would be good.

[JelleZijlstra]

@carljm could you say more about what behavior you'd like to see instead of setting __annotate__ to None when __annotations__ is set? This is about the behavior specified in the last few paragraphs of https://peps.python.org/pep-0649/#annotate-and-annotations, where setting either __annotate__ or __annotations__ directly invalidates the other. The behavior is a little convoluted, but it does make sense to me; the two attributes are meant to be in sync, so if you set one explicitly, the other should go away too.

[carljm]

The only behavior change I would make is that setting __annotations__ would have no effect on __annotate__. Otherwise I wouldn't change anything (I think that setting __annotate__ should invalidate __annotations__, as specified.)

__annotations__ is derived from __annotate__, not the other way around; __annotate__ is the source of truth. That makes a much stronger argument for invalidating __annotations__ when __annotate__ is set, than the other way around. Throwing away the generated __annotate__ is throwing away the source of truth about the annotations actually given in the source code.

The rationale is to "keep them in sync," but that's not actually possible. Arbitrary mutations can be made to __annotations__ dict (without setting the attribute itself). Any such mutation will make __annotations__ be out of sync with __annotate__, but we don't/can't set __annotate__ to None in this case; only if the __annotations__ attribute is actually re-assigned. This feels arbitrary.

I don't see a strong argument for irretrievably throwing away the source of truth about the source annotations, when it doesn't even allow us to make any guarantees about __annotate__ and __annotations__ staying in sync.

(But I also think this is an edge case, and I don't feel strongly enough to make a fuss about it. If we implement what's specified in PEP 649, it can always be changed later if it causes people problems in practice.)

[JelleZijlstra]

@carljm @AlexWaygood I think I'm nearly ready to submit this PEP to the peps repo. It will be 748 rather than 749, but that's OK; I feel most of the implementation work is done for the moment, and I'd like to give people an opportunity to give feedback on all the proposals in the draft.

If you have some time, I'd be grateful for any feedback on the draft (https://github.com/JelleZijlstra/peps/blob/pep749/peps/pep-0749.rst); if you don't have time or would prefer to wait until the PR is submitted to the peps repo, that's OK too.

[carljm]

My notes:

• I still find the reference to dataclass.dataclasses (not qualified by any particular Python version) as an example of a decorator that "eagerly evaluates annotations" and would break if PEP 563 were replaced immediately by 649, to be confusing/misleading, given that in any Python version where this could happen, we would fix dataclass.dataclasses to still support forward references. I think if it's important to use dataclass.dataclasses as an example, it's important to also clarify this, so as not to give the impression that PEP 563 will still be required for dataclasses to support forward references in the future.
• It was slightly jarring to me to have a Rationale section open with "annotations.ForwardRef replaces typing.ForwardRef", which initially sounds very much like a Specification. I would find it more natural to open this section with discussing what PEP 649 specifies (i.e. the second paragraph), and work the discussion from the first para (i.e. all but the opening sentence of the first para) into the existing second para. And then move from that rationale for why the 649 status quo is insufficient, into a discussion of what we propose to do instead.
• In the description of call_evaluate_function, I'm not sure what "does not rely on the function returning a string" is in reference to. It seems to imply that call_annotate_function relies on some function returning a string, but I don't understand which function it expects to return a string.
• You could explicitly mention that the multiple stdlib uses (dataclasses, NamedTuple) will help us ensure that the initial annotations module API is in reasonable shape for public use.
• It struck me as slightly odd that the rejected alternative "develop outside stdlib" mentioned only dataclasses as stdlib use case, and the "develop with private name" rejected alternative mentioned only NamedTuple. Might be clearer to aim for a roughly complete list of expected stdlib clients, and only give that list once.
• There seems to be a typo in the phrase "cache it in the wrapper'sake dict"
• Also in "To enable introspection the same kinds of introspection" in the PEP 695 section

[JelleZijlstra]

Thanks for the feedback! I'll incorporate this later today.

I still find the reference to dataclass.dataclasses (not qualified by any particular Python version) as an example of a decorator that "eagerly evaluates annotations" and would break if PEP 563 were replaced immediately by 649, to be confusing/misleading

I think you're referring to the "Rejected alternatives" section in the part about from __future__ import annotations? I reworded a discussion of dataclasses elsewhere in the doc, but in hindsight this was probably the part you were talking about last time too. I'll now reword the discussion of dataclasses in this section.

[carljm]

Oops, yeah, sorry for the lack of clarity! That's the problem with reviewing without inline commenting.

[JelleZijlstra]

Updates are in this commit: ec565d7.

[JelleZijlstra]

Let's continue the conversation at python#3814.