PEP 749: Close open issues, other updates (#4289)

Author: JelleZijlstra

peps/pep-0749.rst

@@ -109,7 +109,7 @@ This is expected to be a common pattern, so we cannot afford to break such code
 the upgrade from 3.13 to 3.14.
 
 Such code would still break when the future import is eventually removed. However, this
-is many years in the future, giving affected decorators plenty of time to update their code.
+is many years in the future, giving affected libraries plenty of time to update their code.
 
 *Immediately deprecate the future import*: Instead of waiting until Python 3.13 reaches
 its end-of-life, we could immediately start emitting warnings when the future import is
@@ -185,10 +185,9 @@ Specification
 A new module, ``annotationlib``, is added to the standard library. Its aim is to
 provide tooling for introspecting and wrapping annotations.
 
-The exact contents of the module are not yet specified. We will add support for
-:pep:`649` semantics to standard library functionality that uses annotations, such
-as :py:mod:`dataclasses` and :py:class:`typing.TypedDict`, and use the experience
-to inform the design of the new module.
+The design of the module is informed by the experience of updating the standard
+library (e.g., :py:mod:`dataclasses` and :py:class:`typing.TypedDict`) to use
+:pep:`649` semantics.
 
 The module will contain the following functionality:
 
@@ -251,10 +250,10 @@ Contrary to :pep:`649`, the annotation formats (``VALUE``, ``FORWARDREF``, and `
 will not be added as global members of the :py:mod:`inspect` module. The only recommended
 way to refer to these constants will be as ``annotationlib.Format.VALUE``.
 
-Open issues
------------
+Rejected alternatives
+---------------------
 
-What should this module be called? Some ideas:
+*Use a different name*: Naming is hard, and I considered several ideas:
 
 - ``annotations``: The most obvious name, but it may cause confusion with the existing
   ``from __future__ import annotations``, because users may have both ``import annotations``
@@ -276,8 +275,7 @@ What should this module be called? Some ideas:
 - ``annotationlib``: Similar to the above, but one character shorter and subjectively reads
   better. Also not taken on PyPI.
 
-Rejected alternatives
----------------------
+``annotationlib`` appears to be the best option.
 
 *Add the functionality to the inspect module*: As described above, the
 :py:mod:`inspect` module is already quite large, and its import time is prohibitive
@@ -802,15 +800,10 @@ Signature of ``__annotate__`` functions
   ``__annotate__(format: int) -> dict``
 
 However, using ``format`` as a parameter name could lead to collisions
-if an annotation uses a symbol named ``format``. The parameter should be
-positional-only and have a name that cannot be a legal identifier in order
-to avoid this problem.
-
-The current implementation uses the name ``.format`` with a leading
-dot, but the exact name should be considered an implementation detail
-and cannot be relied upon.
-
-The documentation may still use the name ``format`` for simplicity.
+if an annotation uses a symbol named ``format``. To avoid this problem,
+the current implementation uses a positional-only parameter that is named
+``format`` in the function signature, but that does not shadow use of the name
+``format`` within the annotation.
 
 Backwards Compatibility
 =======================
@@ -874,17 +867,8 @@ who need to interact programmatically with annotations.
 Reference Implementation
 ========================
 
-The in-progress PR `#119891 <https://github.com/python/cpython/pull/119891>`__
-implements much of this PEP.
-
-Open Issues
-===========
-
-We may discover additional areas where :pep:`649` needs clarification or amendment
-as we make progress on implementing it. Readers are encouraged to follow the
-`CPython issue <https://github.com/python/cpython/issues/119180>`__ tracking the
-implementation of the PEP and try out the draft implementation. Any feedback may
-be incorporated into future versions of this PEP.
+The changes proposed in this PEP have been implemented on the main branch
+of the CPython repository.
 
 Acknowledgments
 ===============
@@ -895,7 +879,8 @@ initial decisions, but the overall design is still his.
 I thank Carl Meyer and Alex Waygood for feedback on early drafts of this PEP. Alex Waygood,
 Alyssa Coghlan, and David Ellis provided insightful feedback and suggestions on the
 interaction between metaclasses and ``__annotations__``. Larry Hastings also provided useful
-feedback on this PEP.
+feedback on this PEP. Nikita Sobolev made various changes to the standard library that make
+use of PEP 649 functionality, and his experience helped improve the design.
 
 Appendix
 ========