Skip to content

gh-162069: Add optional doc parameter to sentinel - #162070

Open
tmke8 wants to merge 1 commit into
python:mainfrom
tmke8:gh-162069-sentinel-doc
Open

tmke8 wants to merge 1 commit into
python:mainfrom
tmke8:gh-162069-sentinel-doc

Conversation

@tmke8

@tmke8 tmke8 commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Sentinel objects can now be given a docstring with sentinel(name, doc=...). The __doc__ attribute of a sentinel object remains read-only.

>>> MISSING = sentinel("MISSING", doc="No value was provided.")
>>> MISSING.__doc__
'No value was provided.'

Sentinel objects can now be given a docstring with
`sentinel(name, doc=...)`. The `__doc__` attribute of a sentinel object
remains read-only.
@tmke8
tmke8 requested a review from AA-Turner as a code owner November 15, 2026 23:04
@bedevere-app bedevere-app Bot added the type-feature A feature request or enhancement label Nov 15, 2026
@read-the-docs-community

Copy link
Copy Markdown

Documentation build overview

📚 cpython-previews | 🛠️ Build #35913237 | 📁 Comparing ece1b68 against main (d8bc666)

  🔍 Preview build  

3 files changed
± builtins/functions.html
± whatsnew/3.16.html
± whatsnew/changelog.html

Comment thread Doc/whatsnew/3.16.rst
* :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.

?

@@ -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.

Comment thread Objects/sentinelobject.c

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

awaiting review type-feature A feature request or enhancement

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants