Python sentinel() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Python 3.15+

Definition

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:
        ...
CallWhat it does
sentinel("MISSING")A new unique marker named MISSING.
value is MISSINGThe way to test for it.
MISSING is MISSINGTrue: always the same object.
default=MISSINGUse 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

ParameterDescription
nameRequired. A string naming the marker, used for its readable representation.

Return Value

Return ValueDescription
sentinelA 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")

How It Works

  1. Feature detection. On older versions, calling sentinel raises NameError and a tiny class takes its place.
  2. None is data here. "debug" is stored as None and comes back correctly instead of being treated as missing.
  3. Two checks. The marker detects both a missing key and a missing default argument.
  4. 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)

How It Works

  1. Same name, same object. START is START is always True.
  2. Distinct markers. START and END are different objects and are not equal.
  3. Find by identity. m is END is True only for the END marker in the list.
  4. 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]"))

How It Works

  1. Version check. sys.version_info picks the built-in on 3.15+ and object() before that.
  2. Untouched fields. Arguments left at UNSET do not change the profile.
  3. Clearing is allowed. phone=None is a real request to clear the phone, and it is honoured.
  4. 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.

Next: slice()

Create a reusable slice object like [start:stop:step].

slice() →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

14 people found this page helpful