Text of peps.python.org › pep-0661 as Styx crawled it on Nov 18, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

PEP 661 – Sentinel Values | peps.python.org

PEP 661 – Sentinel Values PEP 661 – Sentinel Values Author : Tal Einat <tal at python.org>, Jelle Zijlstra <jelle.zijlstra at gmail.com> Discussions-To : Discourse thread Status : Final Type : Standards Track Created : 06-Jun-2021 Python-Version : 3.15 Post-History : 20-May-2021 , 06-Jun-2021 Resolution : 23-Apr-2026 Table of Contents Abstract Motivation Rationale Specification Typing C API Backwards Compatibility How to Teach This Security Implications Reference Implementation Rejected Ideas Use NotGiven = object() Add a single new sentinel value, such as MISSING or Sentinel Use the existing Ellipsis sentinel value Use a single-valued enum A sentinel class decorator Using class objects Define a recommended “standard” idiom, without supplying an implementation Use a new standard library module Use a registry of per-module sentinel names Automatically discover or pass a module name Allowing customization of boolean evaluation Using typing.Literal in type annotations Additional Notes Footnotes Copyright Important This PEP is a historical document.

The up-to-date, canonical documentation can now be found at sentinel . × See PEP 1 for how to propose changes. Abstract Unique placeholder values, commonly known as “sentinel values”, are common in programming. They have many uses, such as for: Default values for function arguments, for when a value was not given: def foo ( value = None ): ... Return values from functions when something is not found or unavailable: >>> "abc" . find ( "d" ) -1 Missing data, such as NULL in relational databases or “N/A” (“not available”) in spreadsheets Python has the special value None , which is intended to be used as such a sentinel value in most cases.

However, sometimes an alternative sentinel value is needed, usually when it needs to be distinct from None since None is a valid value in that context. Such cases are common enough that several idioms for implementing such sentinels have arisen over the years, but uncommon enough that there hasn’t been a clear need for standardization. However, the common implementations, including some in the stdlib, suffer from several significant drawbacks.

This PEP proposes adding a built-in class for defining sentinel values, to be used in the stdlib and made publicly available to all Python code. Sentinels can be defined in Python with the sentinel() built-in class, and in C with the PySentinel_New() C API function. Note: Changing all existing sentinels in the stdlib to be implemented this way is not deemed necessary, and whether to do so is left to the discretion of the maintainers.

Motivation In May 2021, a question was brought up on the python-dev mailing list [1] about how to better implement a sentinel value for traceback.print_exception . The existing implementation used the following common idiom: _sentinel = object () However, this object has an uninformative and overly verbose repr, causing the function’s signature to be overly long and hard to read: >>> help ( traceback . print_exception ) Help on function print_exception in module traceback: print_exception(exc, /, value=<object object at 0x000002825DF09650>, tb=<object object at 0x000002825DF09650>, limit=None, file=None, chain=True) Additionally, two other drawbacks of many existing sentinels were brought up in the discussion: Some do not have a distinct type, hence it is impossible to define clear type signatures for functions with such sentinels as default values.

They behave unexpectedly after being copied, due to a separate instance being created and thus comparisons using is failing. Some common sentinel idioms have similar problems after being pickled and unpickled. In the ensuing discussion, Victor Stinner supplied a list of currently used sentinel values in the Python standard library [2] . This showed that the need for sentinels is fairly common, that there are various implementation methods used even within the stdlib, and that many of these suffer from at least one of the three above drawbacks.

The discussion did not lead to any clear consensus on whether a standard implementation method is needed or desirable, whether the drawbacks mentioned are significant, nor which kind of implementation would be good. The author of this PEP created an issue on bugs.python.org (now a GitHub issue [3] ) suggesting options for improvement, but that focused on only a single problematic aspect of a few cases, and failed to gather any support.

A poll [4] was created on discuss.python.org to get a clearer sense of the community’s opinions. After nearly two weeks, significant further, discussion, and 39 votes, the poll’s results were not conclusive. 40% had voted for “The status-quo is fine / there’s no need for consistency in this”, but most voters had voted for one or more standardized solutions. Specifically, 37% of the voters chose “Consistent use of a new, dedicated sentinel factory / class / meta-class, also made publicly available in the stdlib”.

With such mixed opinions, this PEP was created to facilitate making a decision on the subject. While working on this PEP, iterating on various options and implementations and continuing discussions, the author has come to the opinion that a simple, good implementation available in the standard library would be worth having, both for use in the standard library itself and elsewhere. Rationale The criteria guiding the chosen implementation were: The sentinel objects should behave as expected by a sentinel object: When compared using the is operator, it should always be considered identical to itself but never to any other object.

Creating a sentinel object should be a simple, straightforward one-liner. It should be simple to define as many distinct sentinel values as needed. The sentinel objects should have a clear and short repr. It should be possible to use clear type signatures for sentinels. The sentinel objects should behave correctly after copying, and sentinels should have predictable behavior when pickled and unpickled. Such sentinels should work when using CPython 3.x and PyPy3, and ideally also with other implementations of Python.

As simple and straightforward as possible, in implementation and especially in use. Avoid this becoming one more special thing to learn when learning Python. It should be easy to find and use when needed, and obvious enough when reading code that one would normally not feel a need to look up its documentation. With so many uses in the Python standard library [2] , it would be useful to have an implementation available to the standard library, since the stdlib cannot use implementations of sentinel objects available elsewhere (such as the sentinels [5] or sentinel [6] PyPI packages).

After researching existing idioms and implementations, and going through many different possible implementations, the design below was chosen to meet these criteria while keeping the API and implementation small (see Reference Implementation ). To support common use cases, we add two customization points: The repr argument can be used to customize the repr() of sentinels. Many pre-existing sentinels in the standard library use a custom repr like <missing> , and this argument allows us to convert these sentinels to the new API while preserving this behavior.

The __module__ attribute of sentinels is writable, allowing users to control the module used for pickling in some unusual cases, such as sentinels created through exec() . This aligns with the behavior of other built-in types with a __module__ attribute, including classes, functions, TypeVar objects, and (as of Python 3.15) type aliases. Specification A new built-in callable named sentinel will be added. >>> MISSING = sentinel ( 'MISSING' ) >>> MISSING MISSING sentinel() takes a single required positional-only argument, name , which must be a str , and an optional keyword-only argument, repr .

Passing a non-string as the name raises TypeError . The name is used as the sentinel

The rest of this page is on the live site.