Skip to content

Add an optional doc parameter to sentinel #162069

Open

Description

@tmke8

Feature or enhancement

I propose adding an optional keyword-only doc parameter to the sentinel constructor, so that individual sentinels can have a docstring:

UNKNOWN = sentinel("UNKNOWN", doc="Represents a value that cannot be calculated.")
>>> UNKNOWN.__doc__
'Represents a value that cannot be calculated.'
>>> sentinel("MISSING").__doc__ is None
True

The signature would then be sentinel(name, /, *, repr=None, doc=None).

Motivation

Sentinels are often part of a module's public API, but there is currently no way to attach documentation to one at runtime. Currently, __doc__ on a sentinel object is read-only and returns the __doc__ on the sentinel constructor itself:

>>> UNKNOWN = sentinel("UNKNOWN")
>>> UNKNOWN.__doc__
'Create a unique sentinel object with the given name.'
>>> UNKNOWN.__doc__ = "Represents a value that cannot be calculated."
AttributeError: 'sentinel' object attribute '__doc__' is read-only

I originally suggested making __doc__ writable, but I now think a constructor argument is better, because:

  • A string literal in the sentinel(...) call is easy for static tools to find, for example for hover text in an IDE.
  • Sentinels are otherwise fixed at construction (__name__ and the repr are read-only), so having __doc__ be the same makes sense.
  • There is precedent in property(fget, doc=...) and dataclasses.field(doc=...).

Proposed behaviour

  1. Default is None. I think there is precedence for this. (This is technically a breaking change in the sense that previously, __doc__ on a sentinel object was guaranteed to be a string, and now isn't, but I hope that's okay.)
  2. __doc__ is read-only on sentinel objects. Could be relaxed later.

C API

If __doc__ is read-only, there is no way to set a docstring on a sentinel created with PySentinel_New(). One could therefore add

PyObject *PySentinel_NewWithDoc(const char *name, const char *module_name,
                                const char *repr, const char *doc);

following the naming of PyErr_NewExceptionWithDoc().

Has this already been discussed elsewhere?

I have already discussed this feature proposal on Discourse

Links to previous discussion of this feature:

https://discuss.python.org/t/make-doc-on-sentinels-writable/109067

Linked PRs

Activity

  1. picnixz commented on Nov 16, 2026

    @picnixz
    Member

    I wished we actually implemented sentinels via a keyword rather than a builtin so that we can also support docs at the code level directly (like class) but the ship has sailed so it is ok. Since we can specify __repr__ in rhe constructor, having the doc as a constructor argument also makes sense.

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    interpreter-core(Objects, Python, Grammar, and Parser dirs)type-featureA feature request or enhancement

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions