gh-148829: Implement PEP 661 by JelleZijlstra · Pull Request #148831 · python/cpython

JelleZijlstra · 2026-04-21T13:59:21Z

Replaces JelleZijlstra#4. See python/steering-council#258.

Issue: Implement PEP 661 Sentinel Values #148829

📚 Documentation preview 📚: https://cpython-previews--148831.org.readthedocs.build/

Co-authored-by: Victorien <65306057+Viicos@users.noreply.github.com>

Co-authored-by: Pieter Eendebak <pieter.eendebak@gmail.com>

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

bedevere-bot · 2026-04-24T13:59:52Z

🤖 New build scheduled with the buildbot fleet by @JelleZijlstra for commit 53a84b6 🤖

Results will be shown at:

https://buildbot.python.org/all/#/grid?branch=refs%2Fpull%2F148831%2Fmerge

If you want to schedule another build, you need to add the 🔨 test-with-buildbots label again.

ZeroIntensity

The C code and the corresponding documentation look good to me. I didn't look very closely at the tests.

sunmy2019

LGTM

sunmy2019

Clarify the pickle document. So that people will see X = sentinel("Y") is not picklable.

JelleZijlstra · 2026-04-24T16:48:50Z

Buildbot run: A few failures look unrelated

In file included from ./Include/internal/pycore_backoff.h:12,
                 from ./Include/internal/pycore_code.h:11,
                 from ./Include/internal/pycore_call.h:11,
                 from ./Modules/_ctypes/_ctypes.c:109:
./Modules/_ctypes/_ctypes.c: In function ‘set_stginfo_ffi_type_pointer’:
./Modules/_ctypes/_ctypes.c:2234:40: error: ‘FFI_TYPE_COMPLEX’ undeclared (first use in this function); did you mean ‘FFI_TYPE_DOUBLE’?
         assert(fmt->pffi_type->type == FFI_TYPE_COMPLEX);
                                        ^~~~~~~~~~~~~~~~
./Modules/_ctypes/_ctypes.c:2234:40: note: each undeclared identifier is reported only once for each function it appears in

But I also see

Traceback (most recent call last):
  File "/home/ubuntu/buildarea/pull_request.stan-aarch64-ubuntu.oddballs/build/Lib/test/pickletester.py", line 3254, in test_builtin_types
    s = self.dumps(t, proto)
  File "/home/ubuntu/buildarea/pull_request.stan-aarch64-ubuntu.oddballs/build/Lib/test/test_xpickle.py", line 190, in dumps
    return self.send_to_worker(python, data)
           ~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^
  File "/home/ubuntu/buildarea/pull_request.stan-aarch64-ubuntu.oddballs/build/Lib/test/test_xpickle.py", line 172, in send_to_worker
    raise exception
AttributeError: Can't get attribute 'sentinel' on <module 'builtins' (built-in)>

https://buildbot.python.org/#/builders/1865/builds/54

Which is a bit mysterious, is this looking at the builtins of another build?

sunmy2019 · 2026-04-24T16:54:21Z

Which is a bit mysterious, is this looking at the builtins of another build?

Yes. We need to patch this test. It tests pickle compatiblity acrosses python versions.

./python -m test test_xpickle -m test_builtin_types -u xpickle

sunmy2019 · 2026-04-24T16:55:46Z

diff --git a/Lib/test/pickletester.py b/Lib/test/pickletester.py
index 6366f12257..c2018c9785 100644
--- a/Lib/test/pickletester.py
+++ b/Lib/test/pickletester.py
@@ -3244,6 +3244,7 @@ def test_builtin_types(self):
             'BuiltinImporter': (3, 3),
             'str': (3, 4),  # not interoperable with Python < 3.4
             'frozendict': (3, 15),
+            'sentinel': (3, 15),
         }
         for t in builtins.__dict__.values():
             if isinstance(t, type) and not issubclass(t, BaseException):

sunmy2019 · 2026-04-24T17:14:44Z

Buildbot run: A few failures look unrelated

I opened #148967 to track it.

picnixz · 2026-04-24T20:23:40Z

+   *name* and :attr:`~sentinel.__module__` set to *module_name*.
+   Return ``NULL`` with an exception set on failure.
+
+   *module_name* should be the name of an importable module if the sentinel


Please mention whether NULL is allowed for module_name to indicate that the sentinel doesn't support pickle.

It is not. Should we support this?

We might as well, since we already set the module to None if caller() doesn't find anything.

JelleZijlstra · 2026-04-25T03:03:22Z

Thanks for the feedback! Pushed a new version.

picnixz · 2026-04-25T14:34:17Z

+class SentinelTest(unittest.TestCase):
+
+    def test_pysentinel_new(self):
+        import pickle


I think you can put this at the top-level. It's not really important that imports are fast in test modules.

picnixz · 2026-04-25T14:42:34Z

+
+   .. attribute:: __name__
+
+      The sentinel's name.
+
+   .. attribute:: __module__
+
+      The name of the module where the sentinel was created.


Maybe indicate something like "A sentinel object exposes the following read-only attributes" so that the paragraph about pickle is not glued to it.

picnixz · 2026-04-25T14:43:19Z

+        support.gc_collect()
+        self.assertIsNone(ref())
+
+    def test_sentinel_union(self):


Maybe add a test where the RHS/LHS is not a type?

picnixz · 2026-04-25T14:43:40Z

+        with self.assertRaises(AttributeError):
+            missing.__module__ = "changed"


Maybe add tests to check that we can't delete those attributes either

sunmy2019 · 2026-04-25T15:04:23Z

+   Sentinels importable from their defining module by name preserve their
+   identity when pickled and unpickled.  Sentinels that are not importable by
+   module and name are not picklable.


How about move this paragraph down to the pickle part?

Actually this is mostly redundant with the later pickle paragraph, I'll remove most of it.

JelleZijlstra and others added 11 commits April 16, 2026 20:45

Initial implementation of PEP 661 v2 (sentinels)

559e527

Update Doc/library/functions.rst

ededfb7

Co-authored-by: Victorien <65306057+Viicos@users.noreply.github.com>

Update Doc/library/functions.rst

39f364c

Co-authored-by: Victorien <65306057+Viicos@users.noreply.github.com>

gc, name

0adf314

C API

e4a106a

not needed

e5b8789

use it for NoExtraItems

bdcb400

tweaks

cc4545c

fix warning?

be58215

blurb

91de05b

attribute

4a970a6

JelleZijlstra requested review from a team, AA-Turner, AlexWaygood, ZeroIntensity, emmatyping, ericsnowcurrently and erlend-aasland as code owners April 21, 2026 13:59

bedevere-app Bot added the awaiting core review label Apr 21, 2026

bedevere-app Bot mentioned this pull request Apr 21, 2026

Implement PEP 661 Sentinel Values #148829

Open

JelleZijlstra added the DO-NOT-MERGE label Apr 21, 2026

JelleZijlstra mentioned this pull request Apr 21, 2026

PEP 661 -- Sentinel Values python/steering-council#258

Closed

5 tasks

johnslavik self-requested a review April 22, 2026 09:44

eendebakpt reviewed Apr 22, 2026

View reviewed changes

Comment thread Objects/sentinelobject.c Outdated

Comment thread Lib/typing.py

eendebakpt reviewed Apr 22, 2026

View reviewed changes

Comment thread Objects/sentinelobject.c Outdated

eendebakpt reviewed Apr 22, 2026

View reviewed changes

Comment thread Objects/sentinelobject.c Outdated

ZeroIntensity reviewed Apr 22, 2026

View reviewed changes

Comment thread Objects/sentinelobject.c Outdated

Comment thread Objects/sentinelobject.c Outdated

Comment thread Objects/sentinelobject.c

Comment thread Objects/sentinelobject.c

refactors

9cfd101

eendebakpt reviewed Apr 22, 2026

View reviewed changes

Comment thread Objects/sentinelobject.c Outdated

Update Objects/sentinelobject.c

a851235

Co-authored-by: Pieter Eendebak <pieter.eendebak@gmail.com>

fix

2beb1c2

sunmy2019 self-requested a review April 23, 2026 19:42

JelleZijlstra removed the DO-NOT-MERGE label Apr 24, 2026

Merge branch 'main' into pep661

e2d92a1

hugovk reviewed Apr 24, 2026

View reviewed changes

Comment thread Doc/c-api/sentinel.rst Outdated

Update Doc/c-api/sentinel.rst

53a84b6

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

JelleZijlstra added the 🔨 test-with-buildbots Test PR w/ buildbots; report in status section label Apr 24, 2026

bedevere-bot removed the 🔨 test-with-buildbots Test PR w/ buildbots; report in status section label Apr 24, 2026

ZeroIntensity approved these changes Apr 24, 2026

View reviewed changes

bedevere-app Bot added awaiting merge and removed awaiting core review labels Apr 24, 2026

sunmy2019 reviewed Apr 24, 2026

View reviewed changes

Comment thread Objects/sentinelobject.c

sunmy2019 approved these changes Apr 24, 2026

View reviewed changes

sunmy2019 reviewed Apr 24, 2026

View reviewed changes

Comment thread Doc/c-api/sentinel.rst Outdated

Comment thread Doc/library/functions.rst Outdated

picnixz reviewed Apr 24, 2026

View reviewed changes

JelleZijlstra added 2 commits April 24, 2026 19:27

Merge remote-tracking branch 'upstream/main' into pep661

396356e

feedback

bfa98a1

JelleZijlstra added 2 commits April 24, 2026 23:00

add assert

465061a

another one

70c04a2

picnixz reviewed Apr 25, 2026

View reviewed changes

sunmy2019 reviewed Apr 25, 2026

View reviewed changes

more tweaks

7c276c5

		with self.assertRaises(AttributeError):
		missing.__module__ = "changed"

Uh oh!

Conversation

JelleZijlstra commented Apr 21, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bedevere-bot commented Apr 24, 2026

Uh oh!

ZeroIntensity left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sunmy2019 left a comment

Choose a reason for hiding this comment

Uh oh!

sunmy2019 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

JelleZijlstra commented Apr 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sunmy2019 commented Apr 24, 2026

Uh oh!

sunmy2019 commented Apr 24, 2026

Uh oh!

sunmy2019 commented Apr 24, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

JelleZijlstra commented Apr 25, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

JelleZijlstra commented Apr 21, 2026 •

edited by github-actions Bot

Loading

sunmy2019 left a comment •

edited

Loading

JelleZijlstra commented Apr 24, 2026 •

edited

Loading