Make `__doc__` on sentinels writable

Ideas
1

(partly inspired by the discussion in this thread)

This seems useful to be able to do:

UNKNOWN = sentinel("UNKNOWN")
UNKNOWN.__doc__ = "Sentinel to represent values that cannot be calculated"

so that, e.g., sphinx can pick up the docstring.

However, currently this happens:

Python 3.15.0rc2 (main, Sep  1 2026, 14:05:48) [Clang 22.1.3 ] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> UNKNOWN = sentinel("UNKNOWN")
>>> UNKNOWN.__doc__ = "Sentinel to represent values that cannot be calculated"
Traceback (most recent call last):
  File "<python-input-1>", line 1, in <module>
    UNKNOWN.__doc__ = "Sentinel to represent values that cannot be calculated"
    ^^^^^^^^^^^^^^^
AttributeError: 'sentinel' object attribute '__doc__' is read-only
>>> UNKNOWN.__doc__
'Create a unique sentinel object with the given name.'

This might just be a limitation of the implementation, in which case there’s nothing we can do, but if it is in fact possible to make __doc__ writable, I think that would be a good idea.

1 Like
2

As a Sphinx maintainer it would make sense indeed. In the meantime, you should be able to make it work via inline doc syntax using #: comments above IIRC.

cc @Jelle

1 Like
3

Or allow it to be a passed parameter.

The reference implementation has a snag, because the class defines __slots__, the docstring on the class must be dropped, such that a slot for __doc__ can be added to the instance. This is something I’ve hit on a few occasions when creating descriptors that define __slots__. Would certainly be nice to allow a class to have a docstring and let a slotted instance define a __doc__.

The other technical hiccup here, I am not sure how __doc__ is inferred for sentinals. I know that descriptors (specifically, anything that defines __get__), have some special casing where help() looks at the instance __doc__, or at least it appears to operate that way.

1 Like
4

Since sentinel objects are read-only, I think that it would be better do add a new optional doc parameter to its documentation.

2 Likes
5

That’s also completely fine with me, though note that __module__ is actually already writable: PEP 661 -- Sentinel Values · Issue #258 · python/steering-council · GitHub

1 Like
6

Sentinels do not currently support per-instance docstrings; there’s no place to store them on the object. The __doc__ attribute referenced in the error message above is the doc for the sentinel class.

Adding per-instance docstrings would be possible, but it would be a new feature and it’s probably too late for Python 3.15.