Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 14 additions & 1 deletion Doc/builtins/functions.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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::
Expand All @@ -1950,6 +1950,12 @@ are always available. They are listed here in alphabetical order.
>>> MISSING
<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.

Expand Down Expand Up @@ -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, /)
Expand Down
6 changes: 6 additions & 0 deletions Doc/whatsnew/3.16.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why not this:

Suggested change
:class:`!sentinel` class.
:class:`sentinel` class.

?

(Contributed by Thomas M Kehrenberg in :gh:`162069`.)


Default interactive shell
=========================
Expand Down
17 changes: 17 additions & 0 deletions Lib/test/test_builtin.py
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand Down
1 change: 1 addition & 0 deletions Lib/test/test_capi/test_object.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
Original file line number Diff line number Diff line change
@@ -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.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same:

Suggested change
``None`` by default, instead of the docstring of the :class:`!sentinel` class.
``None`` by default, instead of the docstring of the :class:`sentinel` class.

24 changes: 16 additions & 8 deletions Objects/clinic/sentinelobject.c.h

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

20 changes: 14 additions & 6 deletions Objects/sentinelobject.c
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ typedef struct {
PyObject *name;
PyObject *module;
PyObject *repr;
PyObject *doc;
} sentinelobject;

#define sentinelobject_CAST(op) \
Expand Down Expand Up @@ -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));

Expand All @@ -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;
}
Expand All @@ -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;
Expand All @@ -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;
}
Expand Down Expand Up @@ -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);

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably we should replace PySentinel_New() with some new PySentinel_NewEx(), having new argument. Or introduce new C-API function to set __doc__ attribute.

Py_DECREF(module_obj);
Py_DECREF(name_obj);
Py_XDECREF(repr_obj);
Expand All @@ -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;
}

Expand All @@ -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;
}

Expand Down Expand Up @@ -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}
};

Expand All @@ -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.");

Expand Down
Loading