From ece1b68e41dc84efc0cd0af9bc9cc66cb75988e8 Mon Sep 17 00:00:00 2001 From: Thomas M Kehrenberg Date: Sun, 15 Nov 2026 23:53:18 +0100 Subject: [PATCH] gh-162069: Add optional `doc` parameter to `sentinel` Sentinel objects can now be given a docstring with `sentinel(name, doc=...)`. The `__doc__` attribute of a sentinel object remains read-only. --- Doc/builtins/functions.rst | 15 +++++++++++- Doc/whatsnew/3.16.rst | 6 +++++ Lib/test/test_builtin.py | 17 +++++++++++++ Lib/test/test_capi/test_object.py | 1 + ...-11-15-23-50-45.gh-issue-162069.Qd7sNe.rst | 3 +++ Objects/clinic/sentinelobject.c.h | 24 ++++++++++++------- Objects/sentinelobject.c | 20 +++++++++++----- 7 files changed, 71 insertions(+), 15 deletions(-) create mode 100644 Misc/NEWS.d/next/Core_and_Builtins/2026-11-15-23-50-45.gh-issue-162069.Qd7sNe.rst diff --git a/Doc/builtins/functions.rst b/Doc/builtins/functions.rst index 717efe50c130744..b614c2c4d6b623a 100644 --- a/Doc/builtins/functions.rst +++ b/Doc/builtins/functions.rst @@ -1935,7 +1935,7 @@ are always available. They are listed here in alphabetical order. :func:`setattr`. -.. class:: sentinel(name, /, *, repr=None) +.. class:: sentinel(name, /, *, repr=None, doc=None) Return a new unique sentinel object. *name* must be a :class:`str`, and is used by default as the returned object's representation:: @@ -1950,6 +1950,12 @@ are always available. They are listed here in alphabetical order. >>> MISSING + The optional *doc* argument can be used to give the sentinel a docstring:: + + >>> MISSING = sentinel("MISSING", doc="No value was provided.") + >>> MISSING.__doc__ + 'No value was provided.' + Sentinel objects are true and compare equal only to themselves. They are intended to be compared with the :keyword:`is` operator. @@ -1995,8 +2001,15 @@ are always available. They are listed here in alphabetical order. The name of the module where the sentinel was created. This attribute is writable. + .. attribute:: __doc__ + + The sentinel's docstring, or ``None`` if no *doc* argument was given. + .. versionadded:: 3.15 + .. versionchanged:: next + Added the *doc* parameter. + .. class:: slice(stop, /) slice(start, stop, step=None, /) diff --git a/Doc/whatsnew/3.16.rst b/Doc/whatsnew/3.16.rst index 33328b2ee005219..b89909e548bc762 100644 --- a/Doc/whatsnew/3.16.rst +++ b/Doc/whatsnew/3.16.rst @@ -139,6 +139,12 @@ Other language changes :func:`asyncio.print_call_graph` can see through them into the awaited code. (Contributed by Kumar Aditya in :gh:`157361`.) +* :class:`sentinel` now accepts an optional *doc* parameter for giving a + sentinel object a docstring. The ``__doc__`` attribute of a sentinel + object is now ``None`` by default, instead of the docstring of the + :class:`!sentinel` class. + (Contributed by Thomas M Kehrenberg in :gh:`162069`.) + Default interactive shell ========================= diff --git a/Lib/test/test_builtin.py b/Lib/test/test_builtin.py index d21de4adc2a98d8..2bad6842dbccf45 100644 --- a/Lib/test/test_builtin.py +++ b/Lib/test/test_builtin.py @@ -2013,6 +2013,23 @@ def test_sentinel_repr(self): with self.assertRaisesRegex(TypeError, "repr.*str or None"): sentinel("BAD_REPR", repr=42) + def test_sentinel_doc(self): + with_doc = sentinel("WITH_DOC", doc="A documented sentinel.") + without_doc = sentinel("WITHOUT_DOC") + explicit_none = sentinel("EXPLICIT_NONE", doc=None) + self.assertEqual(with_doc.__doc__, "A documented sentinel.") + self.assertIsNone(without_doc.__doc__) + self.assertIsNone(explicit_none.__doc__) + # The docstring of the class is not affected. + self.assertIsInstance(sentinel.__doc__, str) + self.assertNotEqual(sentinel.__doc__, with_doc.__doc__) + + with self.assertRaises(AttributeError): + with_doc.__doc__ = "changed" + with self.assertRaises(AttributeError): + del with_doc.__doc__ + self.assertEqual(with_doc.__doc__, "A documented sentinel.") + def test_sentinel_pickle(self): for proto in range(pickle.HIGHEST_PROTOCOL + 1): with self.subTest(protocol=proto): diff --git a/Lib/test/test_capi/test_object.py b/Lib/test/test_capi/test_object.py index ece673dbbec089d..9994f519bc9dce9 100644 --- a/Lib/test/test_capi/test_object.py +++ b/Lib/test/test_capi/test_object.py @@ -76,6 +76,7 @@ def test_pysentinel_new(self): self.assertEqual(marker.__name__, "CAPI_SENTINEL") self.assertEqual(marker.__module__, __name__) self.assertEqual(repr(marker), "CAPI_SENTINEL") + self.assertIsNone(marker.__doc__) no_module = _testcapi.pysentinel_new("NO_MODULE") self.assertIs(type(no_module), sentinel) diff --git a/Misc/NEWS.d/next/Core_and_Builtins/2026-11-15-23-50-45.gh-issue-162069.Qd7sNe.rst b/Misc/NEWS.d/next/Core_and_Builtins/2026-11-15-23-50-45.gh-issue-162069.Qd7sNe.rst new file mode 100644 index 000000000000000..4bde16f8fcfdb50 --- /dev/null +++ b/Misc/NEWS.d/next/Core_and_Builtins/2026-11-15-23-50-45.gh-issue-162069.Qd7sNe.rst @@ -0,0 +1,3 @@ +Add an optional *doc* parameter to :class:`sentinel` for giving a sentinel +object a docstring. The ``__doc__`` attribute of a sentinel object is now +``None`` by default, instead of the docstring of the :class:`!sentinel` class. diff --git a/Objects/clinic/sentinelobject.c.h b/Objects/clinic/sentinelobject.c.h index f8503194ae5c740..124ea5ed1a76bc6 100644 --- a/Objects/clinic/sentinelobject.c.h +++ b/Objects/clinic/sentinelobject.c.h @@ -9,7 +9,8 @@ preserve #include "pycore_modsupport.h" // _PyArg_UnpackKeywords() static PyObject * -sentinel_new_impl(PyTypeObject *type, PyObject *name, PyObject *repr); +sentinel_new_impl(PyTypeObject *type, PyObject *name, PyObject *repr, + PyObject *doc); static PyObject * sentinel_new(PyTypeObject *type, PyObject *args, PyObject *kwargs) @@ -17,7 +18,7 @@ sentinel_new(PyTypeObject *type, PyObject *args, PyObject *kwargs) PyObject *return_value = NULL; #if defined(Py_BUILD_CORE) && !defined(Py_BUILD_CORE_MODULE) - #define NUM_KEYWORDS 1 + #define NUM_KEYWORDS 2 static struct { PyGC_Head _this_is_not_used; PyObject_VAR_HEAD @@ -26,7 +27,7 @@ sentinel_new(PyTypeObject *type, PyObject *args, PyObject *kwargs) } _kwtuple = { .ob_base = PyVarObject_HEAD_INIT(&PyTuple_Type, NUM_KEYWORDS) .ob_hash = -1, - .ob_item = { &_Py_ID(repr), }, + .ob_item = { &_Py_ID(repr), &_Py_ID(doc), }, }; #undef NUM_KEYWORDS #define KWTUPLE (&_kwtuple.ob_base.ob_base) @@ -35,19 +36,20 @@ sentinel_new(PyTypeObject *type, PyObject *args, PyObject *kwargs) # define KWTUPLE NULL #endif // !Py_BUILD_CORE - static const char * const _keywords[] = {"", "repr", NULL}; + static const char * const _keywords[] = {"", "repr", "doc", NULL}; static _PyArg_Parser _parser = { .keywords = _keywords, .fname = "sentinel", .kwtuple = KWTUPLE, }; #undef KWTUPLE - PyObject *argsbuf[2]; + PyObject *argsbuf[3]; 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; + PyObject *doc = Py_None; fastargs = _PyArg_UnpackKeywords(_PyTuple_CAST(args)->ob_item, nargs, kwargs, NULL, &_parser, /*minpos*/ 1, /*maxpos*/ 1, /*minkw*/ 0, /*varpos*/ 0, argsbuf); @@ -62,11 +64,17 @@ sentinel_new(PyTypeObject *type, PyObject *args, PyObject *kwargs) if (!noptargs) { goto skip_optional_kwonly; } - repr = fastargs[1]; + if (fastargs[1]) { + repr = fastargs[1]; + if (!--noptargs) { + goto skip_optional_kwonly; + } + } + doc = fastargs[2]; skip_optional_kwonly: - return_value = sentinel_new_impl(type, name, repr); + return_value = sentinel_new_impl(type, name, repr, doc); exit: return return_value; } -/*[clinic end generated code: output=958842ece254c82f input=a9049054013a1b77]*/ +/*[clinic end generated code: output=1f402633e7dd3f52 input=a9049054013a1b77]*/ diff --git a/Objects/sentinelobject.c b/Objects/sentinelobject.c index 77bffbc397be585..07b1348932341f6 100644 --- a/Objects/sentinelobject.c +++ b/Objects/sentinelobject.c @@ -15,6 +15,7 @@ typedef struct { PyObject *name; PyObject *module; PyObject *repr; + PyObject *doc; } sentinelobject; #define sentinelobject_CAST(op) \ @@ -47,7 +48,8 @@ caller(void) } static PyObject * -sentinel_new_with_module(PyTypeObject *type, PyObject *name, PyObject *module, PyObject *repr) +sentinel_new_with_module(PyTypeObject *type, PyObject *name, PyObject *module, + PyObject *repr, PyObject *doc) { assert(PyUnicode_Check(name)); @@ -58,6 +60,7 @@ sentinel_new_with_module(PyTypeObject *type, PyObject *name, PyObject *module, P self->name = Py_NewRef(name); self->module = Py_NewRef(module); self->repr = Py_XNewRef(repr); + self->doc = Py_NewRef(doc); _PyObject_GC_TRACK(self); return (PyObject *)self; } @@ -70,11 +73,13 @@ sentinel.__new__ as sentinel_new / * repr: object = None + doc: object = None [clinic start generated code]*/ static PyObject * -sentinel_new_impl(PyTypeObject *type, PyObject *name, PyObject *repr) -/*[clinic end generated code: output=1eb7fab52e57d8c8 input=28cab6c468997b35]*/ +sentinel_new_impl(PyTypeObject *type, PyObject *name, PyObject *repr, + PyObject *doc) +/*[clinic end generated code: output=bd628ad189d4a277 input=162bd94d3cd2f6bf]*/ { if (repr == Py_None) { repr = NULL; @@ -84,7 +89,7 @@ sentinel_new_impl(PyTypeObject *type, PyObject *name, PyObject *repr) return NULL; } PyObject *module = caller(); - PyObject *self = sentinel_new_with_module(type, name, module, repr); + PyObject *self = sentinel_new_with_module(type, name, module, repr, doc); Py_DECREF(module); return self; } @@ -114,7 +119,7 @@ PySentinel_New(const char *name, const char *module_name, const char *repr) } PyObject *sentinel = sentinel_new_with_module( - &PySentinel_Type, name_obj, module_obj, repr_obj); + &PySentinel_Type, name_obj, module_obj, repr_obj, Py_None); Py_DECREF(module_obj); Py_DECREF(name_obj); Py_XDECREF(repr_obj); @@ -128,6 +133,7 @@ sentinel_clear(PyObject *op) Py_CLEAR(self->name); Py_CLEAR(self->module); Py_CLEAR(self->repr); + Py_CLEAR(self->doc); return 0; } @@ -146,6 +152,7 @@ sentinel_traverse(PyObject *op, visitproc visit, void *arg) Py_VISIT(self->name); Py_VISIT(self->module); Py_VISIT(self->repr); + Py_VISIT(self->doc); return 0; } @@ -188,6 +195,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), 0}, + {"__doc__", Py_T_OBJECT_EX, offsetof(sentinelobject, doc), Py_READONLY}, {NULL} }; @@ -196,7 +204,7 @@ static PyNumberMethods sentinel_as_number = { }; PyDoc_STRVAR(sentinel_doc, -"sentinel(name, /, *, repr=None)\n" +"sentinel(name, /, *, repr=None, doc=None)\n" "--\n\n" "Create a unique sentinel object with the given name.");