Skip to content

Commit ece1b68

Browse files
committed
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.
1 parent d8bc666 commit ece1b68

7 files changed

Lines changed: 71 additions & 15 deletions

File tree

‎Doc/builtins/functions.rst‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1935,7 +1935,7 @@ are always available. They are listed here in alphabetical order.
19351935
:func:`setattr`.
19361936

19371937

1938-
.. class:: sentinel(name, /, *, repr=None)
1938+
.. class:: sentinel(name, /, *, repr=None, doc=None)
19391939

19401940
Return a new unique sentinel object. *name* must be a :class:`str`, and is
19411941
used by default as the returned object's representation::
@@ -1950,6 +1950,12 @@ are always available. They are listed here in alphabetical order.
19501950
>>> MISSING
19511951
<MISSING>
19521952

1953+
The optional *doc* argument can be used to give the sentinel a docstring::
1954+
1955+
>>> MISSING = sentinel("MISSING", doc="No value was provided.")
1956+
>>> MISSING.__doc__
1957+
'No value was provided.'
1958+
19531959
Sentinel objects are true and compare equal only to themselves. They are
19541960
intended to be compared with the :keyword:`is` operator.
19551961

@@ -1995,8 +2001,15 @@ are always available. They are listed here in alphabetical order.
19952001

19962002
The name of the module where the sentinel was created. This attribute is writable.
19972003

2004+
.. attribute:: __doc__
2005+
2006+
The sentinel's docstring, or ``None`` if no *doc* argument was given.
2007+
19982008
.. versionadded:: 3.15
19992009

2010+
.. versionchanged:: next
2011+
Added the *doc* parameter.
2012+
20002013

20012014
.. class:: slice(stop, /)
20022015
slice(start, stop, step=None, /)

‎Doc/whatsnew/3.16.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -139,6 +139,12 @@ Other language changes
139139
:func:`asyncio.print_call_graph` can see through them into the awaited code.
140140
(Contributed by Kumar Aditya in :gh:`157361`.)
141141

142+
* :class:`sentinel` now accepts an optional *doc* parameter for giving a
143+
sentinel object a docstring. The ``__doc__`` attribute of a sentinel
144+
object is now ``None`` by default, instead of the docstring of the
145+
:class:`!sentinel` class.
146+
(Contributed by Thomas M Kehrenberg in :gh:`162069`.)
147+
142148

143149
Default interactive shell
144150
=========================

‎Lib/test/test_builtin.py‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2013,6 +2013,23 @@ def test_sentinel_repr(self):
20132013
with self.assertRaisesRegex(TypeError, "repr.*str or None"):
20142014
sentinel("BAD_REPR", repr=42)
20152015

2016+
def test_sentinel_doc(self):
2017+
with_doc = sentinel("WITH_DOC", doc="A documented sentinel.")
2018+
without_doc = sentinel("WITHOUT_DOC")
2019+
explicit_none = sentinel("EXPLICIT_NONE", doc=None)
2020+
self.assertEqual(with_doc.__doc__, "A documented sentinel.")
2021+
self.assertIsNone(without_doc.__doc__)
2022+
self.assertIsNone(explicit_none.__doc__)
2023+
# The docstring of the class is not affected.
2024+
self.assertIsInstance(sentinel.__doc__, str)
2025+
self.assertNotEqual(sentinel.__doc__, with_doc.__doc__)
2026+
2027+
with self.assertRaises(AttributeError):
2028+
with_doc.__doc__ = "changed"
2029+
with self.assertRaises(AttributeError):
2030+
del with_doc.__doc__
2031+
self.assertEqual(with_doc.__doc__, "A documented sentinel.")
2032+
20162033
def test_sentinel_pickle(self):
20172034
for proto in range(pickle.HIGHEST_PROTOCOL + 1):
20182035
with self.subTest(protocol=proto):

‎Lib/test/test_capi/test_object.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,7 @@ def test_pysentinel_new(self):
7676
self.assertEqual(marker.__name__, "CAPI_SENTINEL")
7777
self.assertEqual(marker.__module__, __name__)
7878
self.assertEqual(repr(marker), "CAPI_SENTINEL")
79+
self.assertIsNone(marker.__doc__)
7980

8081
no_module = _testcapi.pysentinel_new("NO_MODULE")
8182
self.assertIs(type(no_module), sentinel)
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
Add an optional *doc* parameter to :class:`sentinel` for giving a sentinel
2+
object a docstring. The ``__doc__`` attribute of a sentinel object is now
3+
``None`` by default, instead of the docstring of the :class:`!sentinel` class.

‎Objects/clinic/sentinelobject.c.h‎

Lines changed: 16 additions & 8 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎Objects/sentinelobject.c‎

Lines changed: 14 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ typedef struct {
1515
PyObject *name;
1616
PyObject *module;
1717
PyObject *repr;
18+
PyObject *doc;
1819
} sentinelobject;
1920

2021
#define sentinelobject_CAST(op) \
@@ -47,7 +48,8 @@ caller(void)
4748
}
4849

4950
static PyObject *
50-
sentinel_new_with_module(PyTypeObject *type, PyObject *name, PyObject *module, PyObject *repr)
51+
sentinel_new_with_module(PyTypeObject *type, PyObject *name, PyObject *module,
52+
PyObject *repr, PyObject *doc)
5153
{
5254
assert(PyUnicode_Check(name));
5355

@@ -58,6 +60,7 @@ sentinel_new_with_module(PyTypeObject *type, PyObject *name, PyObject *module, P
5860
self->name = Py_NewRef(name);
5961
self->module = Py_NewRef(module);
6062
self->repr = Py_XNewRef(repr);
63+
self->doc = Py_NewRef(doc);
6164
_PyObject_GC_TRACK(self);
6265
return (PyObject *)self;
6366
}
@@ -70,11 +73,13 @@ sentinel.__new__ as sentinel_new
7073
/
7174
*
7275
repr: object = None
76+
doc: object = None
7377
[clinic start generated code]*/
7478

7579
static PyObject *
76-
sentinel_new_impl(PyTypeObject *type, PyObject *name, PyObject *repr)
77-
/*[clinic end generated code: output=1eb7fab52e57d8c8 input=28cab6c468997b35]*/
80+
sentinel_new_impl(PyTypeObject *type, PyObject *name, PyObject *repr,
81+
PyObject *doc)
82+
/*[clinic end generated code: output=bd628ad189d4a277 input=162bd94d3cd2f6bf]*/
7883
{
7984
if (repr == Py_None) {
8085
repr = NULL;
@@ -84,7 +89,7 @@ sentinel_new_impl(PyTypeObject *type, PyObject *name, PyObject *repr)
8489
return NULL;
8590
}
8691
PyObject *module = caller();
87-
PyObject *self = sentinel_new_with_module(type, name, module, repr);
92+
PyObject *self = sentinel_new_with_module(type, name, module, repr, doc);
8893
Py_DECREF(module);
8994
return self;
9095
}
@@ -114,7 +119,7 @@ PySentinel_New(const char *name, const char *module_name, const char *repr)
114119
}
115120

116121
PyObject *sentinel = sentinel_new_with_module(
117-
&PySentinel_Type, name_obj, module_obj, repr_obj);
122+
&PySentinel_Type, name_obj, module_obj, repr_obj, Py_None);
118123
Py_DECREF(module_obj);
119124
Py_DECREF(name_obj);
120125
Py_XDECREF(repr_obj);
@@ -128,6 +133,7 @@ sentinel_clear(PyObject *op)
128133
Py_CLEAR(self->name);
129134
Py_CLEAR(self->module);
130135
Py_CLEAR(self->repr);
136+
Py_CLEAR(self->doc);
131137
return 0;
132138
}
133139

@@ -146,6 +152,7 @@ sentinel_traverse(PyObject *op, visitproc visit, void *arg)
146152
Py_VISIT(self->name);
147153
Py_VISIT(self->module);
148154
Py_VISIT(self->repr);
155+
Py_VISIT(self->doc);
149156
return 0;
150157
}
151158

@@ -188,6 +195,7 @@ static PyMethodDef sentinel_methods[] = {
188195
static PyMemberDef sentinel_members[] = {
189196
{"__name__", Py_T_OBJECT_EX, offsetof(sentinelobject, name), Py_READONLY},
190197
{"__module__", Py_T_OBJECT_EX, offsetof(sentinelobject, module), 0},
198+
{"__doc__", Py_T_OBJECT_EX, offsetof(sentinelobject, doc), Py_READONLY},
191199
{NULL}
192200
};
193201

@@ -196,7 +204,7 @@ static PyNumberMethods sentinel_as_number = {
196204
};
197205

198206
PyDoc_STRVAR(sentinel_doc,
199-
"sentinel(name, /, *, repr=None)\n"
207+
"sentinel(name, /, *, repr=None, doc=None)\n"
200208
"--\n\n"
201209
"Create a unique sentinel object with the given name.");
202210

0 commit comments

Comments
 (0)