Skip to content

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

Open
tmke8 wants to merge 2 commits into
python:mainfrom
tmke8:gh-162069-sentinel-doc
Open

tmke8 wants to merge 2 commits 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

read-the-docs-community Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

Documentation build overview

📚 cpython-previews | 🛠️ Build #35930520 | 📁 Comparing 2f2dac6 against main (d8bc666)

  🔍 Preview build  

4 files changed
± builtins/functions.html
± using/ios.html
± whatsnew/3.16.html
± whatsnew/changelog.html

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

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Yeah, I mentioned that in the issue (with the name PySentinel_NewWithDoc but I'll let you decide the name). Should I add it? I don't really know what the pros and cons of new C constructor vs a setter are...

@edvilme

edvilme commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

I think it should not default __doc__ to None. Currently it does have a default value

>>> MISSING = sentinel("MISSING")
>>> MISSING.__doc__
'Create a unique sentinel object with the given name.'
>>>

However with the current changes, nothing shows up

>>> MISSING = sentinel("MISSING")
>>> MISSING.__doc__
>>>

Edit: Just re-read the issue description. But still think it would be useful to have a default value for people not very familiar with sentinels

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.

3 participants