In Python 3.15 and newer, sentinel("NAME") creates a sentinel: a unique marker object that cannot be confused with any real value. A typical use is a default argument that means “nothing was passed”, distinct from None, which callers may pass on purpose. It was added by PEP 661.
Sentinels are compared with is, because each one is a single, unique object. Before 3.15, the common idiom was MISSING = object(), whose printed form shows a memory address; a named sentinel is meant to print readably instead.
sentinel is a built-in on Python 3.15+, available without an import. New in Python 3.15. On Python 3.14 and older, using it raises NameError: name 'sentinel' is not defined, so every example includes a fallback. This page covers only the basic idea; check the official Python 3.15 documentation for details such as its exact repr, truthiness, and copying behaviour.
Syntax
Create one at module level and compare with is.
python
MISSING = sentinel("MISSING")
def get(key, default=MISSING):
if default is MISSING:
...
Call
What it does
sentinel("MISSING")
A new unique marker named MISSING.
value is MISSING
The way to test for it.
MISSING is MISSING
True: always the same object.
default=MISSING
Use it as a default argument value.
Define each sentinel once, at module level, and import that name wherever you need it.
Library declarations
python
sentinel(name)
# new in Python 3.15 (PEP 661); see the official docs for any further options
Parameters
Parameter
Description
name
Required. A string naming the marker, used for its readable representation.
Return Value
Return Value
Description
sentinel
A new unique sentinel object (Python 3.15+).
Python Examples
Example 1 — Tell "Not Passed" Apart from None
Use a sentinel default (or a fallback on older Python) so that None can be a real value. The output is the same on every version.
python
try:
MISSING = sentinel("MISSING")
except NameError: # Python 3.14 and older
class _MissingType:
def __repr__(self):
return "MISSING"
MISSING = _MissingType()
def get_setting(settings, key, default=MISSING):
value = settings.get(key, MISSING)
if value is MISSING:
if default is MISSING:
raise KeyError(key)
return default
return value
config = {"debug": None, "level": 0}
print(get_setting(config, "debug"))
print(get_setting(config, "level"))
print(get_setting(config, "color", "blue"))
try:
get_setting(config, "color")
except KeyError:
print("color is missing and has no default")
Output
None
0
blue
color is missing and has no default
How It Works
Feature detection. On older versions, calling sentinel raises NameError and a tiny class takes its place.
None is data here. "debug" is stored as None and comes back correctly instead of being treated as missing.
Two checks. The marker detects both a missing key and a missing default argument.
Falsy values survive.0 for level is returned, which a truthiness test would have lost.
Example 2 — Sentinels Are Compared by Identity
Create two markers and check identity, equality, and membership. The output is the same on every version.
python
try:
make_sentinel = sentinel
except NameError: # Python 3.14 and older
def make_sentinel(name):
return type(name, (), {"__repr__": lambda self: name})()
START = make_sentinel("START")
END = make_sentinel("END")
print(START is START, START is END)
print(START == END)
markers = [START, None, END]
print([m is END for m in markers])
print(None in markers, END in markers)
Output
True False
False
[False, False, True]
True True
How It Works
Same name, same object.START is START is always True.
Distinct markers. START and END are different objects and are not equal.
Find by identity.m is END is True only for the END marker in the list.
Fallback with type(). On older versions, type() builds a one-off class with a readable repr.
Example 3 — "Leave Unchanged" vs "Set to None"
Use a sentinel as the default of keyword arguments so callers can clear a field with None. The first line depends on your version.
python
import sys
if sys.version_info >= (3, 15):
UNSET = sentinel("UNSET")
print("using the built-in sentinel()")
else:
UNSET = object()
print("using object() as the fallback")
def update_profile(profile, *, email=UNSET, phone=UNSET):
if email is not UNSET:
profile["email"] = email
if phone is not UNSET:
profile["phone"] = phone
return profile
user = {"email": "[email protected]", "phone": "555-0100"}
print(update_profile(dict(user), phone=None))
print(update_profile(dict(user), email="[email protected]"))
Output
# On Python 3.15+:
using the built-in sentinel()
# On Python 3.14 and older:
using object() as the fallback
# Both versions then print:
{'email': '[email protected]', 'phone': None}
{'email': '[email protected]', 'phone': '555-0100'}
Lines starting with # only label which Python version prints the lines below them; the program does not print them.
How It Works
Version check.sys.version_info picks the built-in on 3.15+ and object() before that.
Untouched fields. Arguments left at UNSET do not change the profile.
Clearing is allowed.phone=None is a real request to clear the phone, and it is honoured.
Never printed. The fallback object() is only compared with is, so no memory address appears.
Frequently Asked Questions
sentinel() is new in Python 3.15 (PEP 661). On 3.14 and older, the name is not defined and you get NameError.
A unique marker object used to signal a special case, such as "no argument given", that must not be confused with real data like None or 0.
Because None is often a valid value that callers pass on purpose. A sentinel keeps "not passed" and "passed None" apart.
Use is: if value is MISSING. Each sentinel is one unique object.
MISSING = object(), or a small class with a readable __repr__, defined once at module level.