gh-148829: Make sentinels' repr and module customizable (#149654)

Implementation of python/peps#4968; still needs SC approval.

diff --git a/Doc/c-api/sentinel.rst b/Doc/c-api/sentinel.rst
index 937cae18e86f5071acc19363e824d440f4347589..b1b7329a5d42c591068d605f78910c280c85f53b 100644 (file)
--- a/Doc/c-api/sentinel.rst
+++ b/Doc/c-api/sentinel.rst
@@ -31,12 +31,12 @@ Sentinel objects
 
    .. versionadded:: 3.15
 
-.. c:function:: PyObject* PySentinel_New(const char *name, const char *module_name)
+.. c:function:: PyObject* PySentinel_New(const char *name, const char *module_name, const char *repr)
 
    Return a new :class:`sentinel` object with :attr:`~sentinel.__name__` set to
    *name* and :attr:`~sentinel.__module__` set to *module_name*.
    *name* must not be ``NULL``. If *module_name* is ``NULL``, :attr:`~sentinel.__module__`
-   is set to ``None``.
+   is set to ``None``. If *repr* is ``NULL``, ``repr()`` returns :attr:`~sentinel.__name__`.
    Return ``NULL`` with an exception set on failure.
 
    For pickling to work, *module_name* must be the name of an importable

diff --git a/Doc/data/refcounts.dat b/Doc/data/refcounts.dat
index 663b79e45eec17dfee43e19be0a6f10bc6a8d39a..60c02aabeb89c5187bddcf8acfeaba8fecd629b7 100644 (file)
--- a/Doc/data/refcounts.dat
+++ b/Doc/data/refcounts.dat
@@ -2040,6 +2040,7 @@ PySeqIter_New:PyObject*:seq:0:
 PySentinel_New:PyObject*::+1:
 PySentinel_New:const char*:name::
 PySentinel_New:const char*:module_name::
+PySentinel_New:const char*:repr::
 
 PySequence_Check:int:::
 PySequence_Check:PyObject*:o:0:

diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 1fed142d81b4f72c854a90bf1553d432b933d1c2..0393e2dc776db4a36c204466ac96a3519b62a52c 100644 (file)
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -1827,15 +1827,21 @@ are always available.  They are listed here in alphabetical order.
       :func:`setattr`.
 
 
-.. class:: sentinel(name, /)
+.. class:: sentinel(name, /, *, repr=None)
 
    Return a new unique sentinel object.  *name* must be a :class:`str`, and is
-   used as the returned object's representation::
+   used by default as the returned object's representation::
 
       >>> MISSING = sentinel("MISSING")
       >>> MISSING
       MISSING
 
+   The optional *repr* argument can be used to specify a different representation::
+
+      >>> MISSING = sentinel("MISSING", repr="<MISSING>")
+      >>> MISSING
+      <MISSING>
+
    Sentinel objects are truthy and compare equal only to themselves.  They are
    intended to be compared with the :keyword:`is` operator.
 
@@ -1879,7 +1885,7 @@ are always available.  They are listed here in alphabetical order.
 
    .. attribute:: __module__
 
-      The name of the module where the sentinel was created.
+      The name of the module where the sentinel was created. This attribute is writable.
 
    .. versionadded:: 3.15
 

diff --git a/Include/cpython/sentinelobject.h b/Include/cpython/sentinelobject.h
index 15643ef966af86e4ecf30902f66415f3b70c1f97..e621d6abbfed8aace739862ef8f6c5d78b360fa4 100644 (file)
--- a/Include/cpython/sentinelobject.h
+++ b/Include/cpython/sentinelobject.h
@@ -16,7 +16,8 @@ PyAPI_DATA(PyTypeObject) PySentinel_Type;
 
 PyAPI_FUNC(PyObject *) PySentinel_New(
     const char *name,
-    const char *module_name);
+    const char *module_name,
+    const char *repr);
 
 #ifdef __cplusplus
 }

diff --git a/Include/internal/pycore_global_objects_fini_generated.h b/Include/internal/pycore_global_objects_fini_generated.h
index 7e6107e54a0ab6cdfeb54ff0fa7a29c3ee3cedb2..99a1ffb8ad5229b7c3f71c997276a330ffa0ece0 100644 (file)
--- a/Include/internal/pycore_global_objects_fini_generated.h
+++ b/Include/internal/pycore_global_objects_fini_generated.h
@@ -2032,6 +2032,7 @@ _PyStaticObjects_CheckRefcnt(PyInterpreterState *interp) {
     _PyStaticObject_CheckRefcnt((PyObject *)&_Py_ID(repeat));
     _PyStaticObject_CheckRefcnt((PyObject *)&_Py_ID(repl));
     _PyStaticObject_CheckRefcnt((PyObject *)&_Py_ID(replace));
+    _PyStaticObject_CheckRefcnt((PyObject *)&_Py_ID(repr));
     _PyStaticObject_CheckRefcnt((PyObject *)&_Py_ID(reqrefs));
     _PyStaticObject_CheckRefcnt((PyObject *)&_Py_ID(require_ready));
     _PyStaticObject_CheckRefcnt((PyObject *)&_Py_ID(reserved));

diff --git a/Include/internal/pycore_global_strings.h b/Include/internal/pycore_global_strings.h
index e0b05dde8fa377663f3044ac69609f694e92b858..d5818402a508cb9e8f6199d6f6c46a9abb56c22f 100644 (file)
--- a/Include/internal/pycore_global_strings.h
+++ b/Include/internal/pycore_global_strings.h
@@ -755,6 +755,7 @@ struct _Py_global_strings {
         STRUCT_FOR_ID(repeat)
         STRUCT_FOR_ID(repl)
         STRUCT_FOR_ID(replace)
+        STRUCT_FOR_ID(repr)
         STRUCT_FOR_ID(reqrefs)
         STRUCT_FOR_ID(require_ready)
         STRUCT_FOR_ID(reserved)

diff --git a/Include/internal/pycore_runtime_init_generated.h b/Include/internal/pycore_runtime_init_generated.h
index 47c6226a7d2216635a50d5a8a34484a231722efd..8227f3fa9eedcf54df1a65f1fd076d40b328a251 100644 (file)
--- a/Include/internal/pycore_runtime_init_generated.h
+++ b/Include/internal/pycore_runtime_init_generated.h
@@ -2030,6 +2030,7 @@ extern "C" {
     INIT_ID(repeat), \
     INIT_ID(repl), \
     INIT_ID(replace), \
+    INIT_ID(repr), \
     INIT_ID(reqrefs), \
     INIT_ID(require_ready), \
     INIT_ID(reserved), \

diff --git a/Include/internal/pycore_unicodeobject_generated.h b/Include/internal/pycore_unicodeobject_generated.h
index acad87c5045338eb1f3bf53382bd3c0aea6ab4e1..cb731e9a688878149d1c7f07213976c213fcd5b7 100644 (file)
--- a/Include/internal/pycore_unicodeobject_generated.h
+++ b/Include/internal/pycore_unicodeobject_generated.h
@@ -2800,6 +2800,10 @@ _PyUnicode_InitStaticStrings(PyInterpreterState *interp) {
     _PyUnicode_InternStatic(interp, &string);
     assert(_PyUnicode_CheckConsistency(string, 1));
     assert(PyUnicode_GET_LENGTH(string) != 1);
+    string = &_Py_ID(repr);
+    _PyUnicode_InternStatic(interp, &string);
+    assert(_PyUnicode_CheckConsistency(string, 1));
+    assert(PyUnicode_GET_LENGTH(string) != 1);
     string = &_Py_ID(reqrefs);
     _PyUnicode_InternStatic(interp, &string);
     assert(_PyUnicode_CheckConsistency(string, 1));

diff --git a/Lib/test/test_builtin.py b/Lib/test/test_builtin.py
index 81967fb8a837404ddb1fcbb7026381b3536ca688..d62a3a4f17f85e3574a3685b7cd1e28b7fdc80bd 100644 (file)
--- a/Lib/test/test_builtin.py
+++ b/Lib/test/test_builtin.py
@@ -1956,16 +1956,33 @@ class BuiltinTest(ComplexesAreIdenticalMixin, unittest.TestCase):
         with self.assertRaises(TypeError):
             class SubSentinel(sentinel):
                 pass
+
+    def test_sentinel_attributes(self):
+        missing = sentinel("MISSING")
         with self.assertRaises(TypeError):
             sentinel.attribute = "value"
         with self.assertRaises(AttributeError):
-            missing.__name__ = "CHANGED"
+            missing.attribute = "value"
         with self.assertRaises(AttributeError):
-            missing.__module__ = "changed"
+            missing.__name__ = "CHANGED"
+        missing.__module__ = "changed"
+        self.assertEqual(missing.__module__, "changed")
         with self.assertRaises(AttributeError):
             del missing.__name__
+        del missing.__module__
         with self.assertRaises(AttributeError):
-            del missing.__module__
+            missing.__module__
+
+    def test_sentinel_repr(self):
+        with_repr = sentinel("WITH_REPR", repr="custom")
+        without_repr = sentinel("WITHOUT_REPR", repr=None)
+        self.assertEqual(repr(with_repr), "custom")
+        self.assertEqual(repr(without_repr), "WITHOUT_REPR")
+        self.assertEqual(str(with_repr), "custom")
+        self.assertEqual(str(without_repr), "WITHOUT_REPR")
+
+        with self.assertRaisesRegex(TypeError, "repr.*str or None"):
+            sentinel("BAD_REPR", repr=42)
 
     def test_sentinel_pickle(self):
         for proto in range(pickle.HIGHEST_PROTOCOL + 1):

diff --git a/Lib/test/test_capi/test_object.py b/Lib/test/test_capi/test_object.py
index e6fd068dc20d8d4c5250311192083381d58c5d85..e5c50902a0118d4517e6ae1f8991704a398f34a7 100644 (file)
--- a/Lib/test/test_capi/test_object.py
+++ b/Lib/test/test_capi/test_object.py
@@ -82,6 +82,12 @@ class SentinelTest(unittest.TestCase):
         self.assertEqual(no_module.__name__, "NO_MODULE")
         self.assertIs(no_module.__module__, None)
 
+        with_repr = _testcapi.pysentinel_new("WITH_REPR", __name__, "custom repr")
+        self.assertIs(type(with_repr), sentinel)
+        self.assertEqual(with_repr.__name__, "WITH_REPR")
+        self.assertEqual(with_repr.__module__, __name__)
+        self.assertEqual(repr(with_repr), "custom repr")
+
         globals()["CAPI_SENTINEL"] = marker
         self.addCleanup(globals().pop, "CAPI_SENTINEL", None)
         self.assertIs(pickle.loads(pickle.dumps(marker)), marker)

diff --git a/Misc/NEWS.d/next/Core_and_Builtins/2026-05-10-16-43-50.gh-issue-148829.gscS14.rst b/Misc/NEWS.d/next/Core_and_Builtins/2026-05-10-16-43-50.gh-issue-148829.gscS14.rst
new file mode 100644 (file)
index 0000000..3f9b1cc
--- /dev/null
+++ b/Misc/NEWS.d/next/Core_and_Builtins/2026-05-10-16-43-50.gh-issue-148829.gscS14.rst
@@ -0,0 +1,2 @@
+:class:`sentinel` objects now support a ``repr=`` argument and their
+:attr:`~sentinel.__module__` attribute is writable.

diff --git a/Modules/_testcapi/object.c b/Modules/_testcapi/object.c
index c62dc1144df6881576cff493c1bf09d06548cd60..09a548fd2e24489de8de135168e7f19a3e5d2818 100644 (file)
--- a/Modules/_testcapi/object.c
+++ b/Modules/_testcapi/object.c
@@ -560,10 +560,11 @@ pysentinel_new(PyObject *self, PyObject *args)
 {
     const char *name;
     const char *module_name = NULL;
-    if (!PyArg_ParseTuple(args, "s|s", &name, &module_name)) {
+    const char *repr = NULL;
+    if (!PyArg_ParseTuple(args, "s|ss", &name, &module_name, &repr)) {
         return NULL;
     }
-    return PySentinel_New(name, module_name);
+    return PySentinel_New(name, module_name, repr);
 }
 
 static PyObject *

diff --git a/Objects/clinic/sentinelobject.c.h b/Objects/clinic/sentinelobject.c.h
index 51fd35a5979e31897ddfbce6547719b50f43ba32..f8503194ae5c74024492f148b9bcfc59992eec50 100644 (file)
--- a/Objects/clinic/sentinelobject.c.h
+++ b/Objects/clinic/sentinelobject.c.h
@@ -2,33 +2,71 @@
 preserve
 [clinic start generated code]*/
 
-#include "pycore_modsupport.h"    // _PyArg_CheckPositional()
+#if defined(Py_BUILD_CORE) && !defined(Py_BUILD_CORE_MODULE)
+#  include "pycore_gc.h"          // PyGC_Head
+#  include "pycore_runtime.h"     // _Py_ID()
+#endif
+#include "pycore_modsupport.h"    // _PyArg_UnpackKeywords()
 
 static PyObject *
-sentinel_new_impl(PyTypeObject *type, PyObject *name);
+sentinel_new_impl(PyTypeObject *type, PyObject *name, PyObject *repr);
 
 static PyObject *
 sentinel_new(PyTypeObject *type, PyObject *args, PyObject *kwargs)
 {
     PyObject *return_value = NULL;
-    PyTypeObject *base_tp = &PySentinel_Type;
+    #if defined(Py_BUILD_CORE) && !defined(Py_BUILD_CORE_MODULE)
+
+    #define NUM_KEYWORDS 1
+    static struct {
+        PyGC_Head _this_is_not_used;
+        PyObject_VAR_HEAD
+        Py_hash_t ob_hash;
+        PyObject *ob_item[NUM_KEYWORDS];
+    } _kwtuple = {
+        .ob_base = PyVarObject_HEAD_INIT(&PyTuple_Type, NUM_KEYWORDS)
+        .ob_hash = -1,
+        .ob_item = { &_Py_ID(repr), },
+    };
+    #undef NUM_KEYWORDS
+    #define KWTUPLE (&_kwtuple.ob_base.ob_base)
+
+    #else  // !Py_BUILD_CORE
+    #  define KWTUPLE NULL
+    #endif  // !Py_BUILD_CORE
+
+    static const char * const _keywords[] = {"", "repr", NULL};
+    static _PyArg_Parser _parser = {
+        .keywords = _keywords,
+        .fname = "sentinel",
+        .kwtuple = KWTUPLE,
+    };
+    #undef KWTUPLE
+    PyObject *argsbuf[2];
+    PyObject * const *fastargs;
+    Py_ssize_t nargs = PyTuple_GET_SIZE(args);
+    Py_ssize_t noptargs = nargs + (kwargs ? PyDict_GET_SIZE(kwargs) : 0) - 1;
     PyObject *name;
+    PyObject *repr = Py_None;
 
-    if ((type == base_tp || type->tp_init == base_tp->tp_init) &&
-        !_PyArg_NoKeywords("sentinel", kwargs)) {
+    fastargs = _PyArg_UnpackKeywords(_PyTuple_CAST(args)->ob_item, nargs, kwargs, NULL, &_parser,
+            /*minpos*/ 1, /*maxpos*/ 1, /*minkw*/ 0, /*varpos*/ 0, argsbuf);
+    if (!fastargs) {
         goto exit;
     }
-    if (!_PyArg_CheckPositional("sentinel", PyTuple_GET_SIZE(args), 1, 1)) {
+    if (!PyUnicode_Check(fastargs[0])) {
+        _PyArg_BadArgument("sentinel", "argument 1", "str", fastargs[0]);
         goto exit;
     }
-    if (!PyUnicode_Check(PyTuple_GET_ITEM(args, 0))) {
-        _PyArg_BadArgument("sentinel", "argument 1", "str", PyTuple_GET_ITEM(args, 0));
-        goto exit;
+    name = fastargs[0];
+    if (!noptargs) {
+        goto skip_optional_kwonly;
     }
-    name = PyTuple_GET_ITEM(args, 0);
-    return_value = sentinel_new_impl(type, name);
+    repr = fastargs[1];
+skip_optional_kwonly:
+    return_value = sentinel_new_impl(type, name, repr);
 
 exit:
     return return_value;
 }
-/*[clinic end generated code: output=7f28fc0bf0259cba input=a9049054013a1b77]*/
+/*[clinic end generated code: output=958842ece254c82f input=a9049054013a1b77]*/

diff --git a/Objects/sentinelobject.c b/Objects/sentinelobject.c
index e7e9f60e3edfbe9336f7777fdb457fd7d4620c89..77bffbc397be585d48c1aa1cb0a0b398f369c153 100644 (file)
--- a/Objects/sentinelobject.c
+++ b/Objects/sentinelobject.c
@@ -14,6 +14,7 @@ typedef struct {
     PyObject_HEAD
     PyObject *name;
     PyObject *module;
+    PyObject *repr;
 } sentinelobject;
 
 #define sentinelobject_CAST(op) \
@@ -46,7 +47,7 @@ caller(void)
 }
 
 static PyObject *
-sentinel_new_with_module(PyTypeObject *type, PyObject *name, PyObject *module)
+sentinel_new_with_module(PyTypeObject *type, PyObject *name, PyObject *module, PyObject *repr)
 {
     assert(PyUnicode_Check(name));
 
@@ -56,6 +57,7 @@ sentinel_new_with_module(PyTypeObject *type, PyObject *name, PyObject *module)
     }
     self->name = Py_NewRef(name);
     self->module = Py_NewRef(module);
+    self->repr = Py_XNewRef(repr);
     _PyObject_GC_TRACK(self);
     return (PyObject *)self;
 }
@@ -66,37 +68,56 @@ sentinel.__new__ as sentinel_new
 
     name: object(subclass_of='&PyUnicode_Type')
     /
+    *
+    repr: object = None
 [clinic start generated code]*/
 
 static PyObject *
-sentinel_new_impl(PyTypeObject *type, PyObject *name)
-/*[clinic end generated code: output=4af55c6048bed30d input=3ab75704f39c119c]*/
+sentinel_new_impl(PyTypeObject *type, PyObject *name, PyObject *repr)
+/*[clinic end generated code: output=1eb7fab52e57d8c8 input=28cab6c468997b35]*/
 {
+    if (repr == Py_None) {
+        repr = NULL;
+    }
+    else if (!PyUnicode_Check(repr)) {
+        _PyArg_BadArgument("sentinel", "argument 'repr'", "str or None", repr);
+        return NULL;
+    }
     PyObject *module = caller();
-    PyObject *self = sentinel_new_with_module(type, name, module);
+    PyObject *self = sentinel_new_with_module(type, name, module, repr);
     Py_DECREF(module);
     return self;
 }
 
 PyObject *
-PySentinel_New(const char *name, const char *module_name)
+PySentinel_New(const char *name, const char *module_name, const char *repr)
 {
     PyObject *name_obj = PyUnicode_FromString(name);
     if (name_obj == NULL) {
         return NULL;
     }
+    PyObject *repr_obj = NULL;
+    if (repr != NULL) {
+        repr_obj = PyUnicode_FromString(repr);
+        if (repr_obj == NULL) {
+            Py_DECREF(name_obj);
+            return NULL;
+        }
+    }
     PyObject *module_obj = module_name == NULL
         ? Py_None
         : PyUnicode_FromString(module_name);
     if (module_obj == NULL) {
         Py_DECREF(name_obj);
+        Py_XDECREF(repr_obj);
         return NULL;
     }
 
     PyObject *sentinel = sentinel_new_with_module(
-        &PySentinel_Type, name_obj, module_obj);
+        &PySentinel_Type, name_obj, module_obj, repr_obj);
     Py_DECREF(module_obj);
     Py_DECREF(name_obj);
+    Py_XDECREF(repr_obj);
     return sentinel;
 }
 
@@ -106,6 +127,7 @@ sentinel_clear(PyObject *op)
     sentinelobject *self = sentinelobject_CAST(op);
     Py_CLEAR(self->name);
     Py_CLEAR(self->module);
+    Py_CLEAR(self->repr);
     return 0;
 }
 
@@ -123,6 +145,7 @@ sentinel_traverse(PyObject *op, visitproc visit, void *arg)
     sentinelobject *self = sentinelobject_CAST(op);
     Py_VISIT(self->name);
     Py_VISIT(self->module);
+    Py_VISIT(self->repr);
     return 0;
 }
 
@@ -130,6 +153,9 @@ static PyObject *
 sentinel_repr(PyObject *op)
 {
     sentinelobject *self = sentinelobject_CAST(op);
+    if (self->repr != NULL) {
+        return Py_NewRef(self->repr);
+    }
     return Py_NewRef(self->name);
 }
 
@@ -161,7 +187,7 @@ static PyMethodDef sentinel_methods[] = {
 
 static PyMemberDef sentinel_members[] = {
     {"__name__", Py_T_OBJECT_EX, offsetof(sentinelobject, name), Py_READONLY},
-    {"__module__", Py_T_OBJECT_EX, offsetof(sentinelobject, module), Py_READONLY},
+    {"__module__", Py_T_OBJECT_EX, offsetof(sentinelobject, module), 0},
     {NULL}
 };
 
@@ -170,7 +196,7 @@ static PyNumberMethods sentinel_as_number = {
 };
 
 PyDoc_STRVAR(sentinel_doc,
-"sentinel(name, /)\n"
+"sentinel(name, /, *, repr=None)\n"
 "--\n\n"
 "Create a unique sentinel object with the given name.");