changes (thanks Daniël Noord!)

Author: JelleZijlstra

peps/pep-0661.rst

@@ -37,8 +37,10 @@ uncommon enough that there hasn't been a clear need for standardization.
 However, the common implementations, including some in the stdlib, suffer from
 several significant drawbacks.
 
-This PEP proposes adding a built-in utility for defining sentinel values, to
+This PEP proposes adding a built-in class for defining sentinel values, to
 be used in the stdlib and made publicly available to all Python code.
+Sentinels can be defined in Python with the ``sentinel()`` built-in class,
+and in C with the ``PySentinel_New()`` C API function.
 
 Note: Changing all existing sentinels in the stdlib to be implemented this
 way is not deemed necessary, and whether to do so is left to the discretion
@@ -117,8 +119,8 @@ The criteria guiding the chosen implementation were:
 3. It should be simple to define as many distinct sentinel values as needed.
 4. The sentinel objects should have a clear and short repr.
 5. It should be possible to use clear type signatures for sentinels.
-6. The sentinel objects should behave correctly after copying, and module-scope
-   sentinels should preserve identity when pickled and unpickled.
+6. The sentinel objects should behave correctly after copying, and sentinels
+   should have predictable behavior when pickled and unpickled.
 7. Such sentinels should work when using CPython 3.x and PyPy3, and ideally
    also with other implementations of Python.
 8. As simple and straightforward as possible, in implementation and especially
@@ -249,6 +251,9 @@ To support usage in type expressions, the runtime implementation
 of sentinel objects should have the ``__or__`` and ``__ror__``
 methods, returning :py:class:`typing.Union` objects.
 
+The Typing Council `supports <https://github.com/python/steering-council/issues/258#issuecomment-2417524379>`_
+this part of the proposal.
+
 C API
 -----
 
@@ -268,6 +273,9 @@ Adding a new builtin means that code which currently relies on the bare name
 ``sentinel`` raising ``NameError`` will instead see the new builtin.  This is
 the usual compatibility consideration for new builtins.  Existing local,
 global, and imported names called ``sentinel`` are unaffected.
+Code that already uses the name ``sentinel`` will have to be adapted to use
+the new builtin and may receive new linter errors from linters that warn
+about collisions with builtin names.
 
 
 How to Teach This
@@ -326,6 +334,10 @@ A sketch of the intended behavior follows::
         def __ror__(self, other):
             return typing.Union[other, self]
 
+A backport `exists <https://typing-extensions.readthedocs.io/en/latest/#typing_extensions.Sentinel>`_
+in the :pypi:`typing-extensions` module, though its behavior does not precisely
+match the current iteration of this PEP.
+
 
 Rejected Ideas
 ==============
@@ -448,7 +460,7 @@ Use a registry of per-module sentinel names
 -------------------------------------------
 
 Earlier drafts proposed making sentinel names unique within each module.  Under
-that design, repeated calls such as ``Sentinel("MISSING")`` from the same
+that design, repeated calls such as ``sentinel("MISSING")`` from the same
 module would return the same object, using a process-global registry keyed by
 module name and sentinel name.
 
@@ -517,10 +529,6 @@ advantages of not requiring an import and being much shorter.
 Additional Notes
 ================
 
-* This PEP and an initial implementation were drafted in a dedicated GitHub
-  repo [7]_.  The implementation should be updated to match this simplified
-  proposal.
-
 * For sentinels defined in a class scope, to avoid potential name clashes,
   or when a qualified repr would be clearer, one should pass the desired
   qualified name explicitly.  For example::