Python 3.15 Preview: Sentinel Values

Know What a Sentinel Value Is

A sentinel value is a value that an algorithm treats as a signal rather than as data. It marks a condition such as “terminating the iteration,” “shutting down the worker thread,” or “nothing was passed.” A sentinel is a marker that your code branches on, and it doesn’t carry any information about the data you’re processing.

Python uses sentinel values in many situations. For example, when you search a string and the target substring isn’t there, you get -1 back:

>>> "Hello, World!".find("z")
-1

In this example, -1 tells you that the substring isn’t there. In other words, your code should read it as a signal rather than as an index pointing to the target substring.

A sentinel can also be a unique object that you create for this purpose, ensuring that nothing else can ever equal it.

The essential idea is that a sentinel value should stay distinct from every legitimate value your data can take. This way, a loop over your data can check each value and branch when it encounters the sentinel:

Now that you know what a sentinel value is, you can start spotting the ones that Python has been handing you all along.

Spot the Sentinels Python Already Uses

You’ve probably been using sentinels since your early Python programs. Using None as the default value for optional arguments is a common example. It typically means “no value was passed.” In a data context, it may mean “no data.”

In the standard library, you’ll also find a variety of sentinels. Here are four modules and some of their sentinel values:

>>> import configparser
>>> configparser._UNSET
<object object at 0x7f6d134cc6f0>

>>> import inspect
>>> inspect.Parameter.empty
<class 'inspect._empty'>

>>> import typing
>>> typing.NoDefault
typing.NoDefault

>>> import unittest.mock
>>> unittest.mock.DEFAULT
sentinel.DEFAULT

Each of these four modules uses a different approach to sentinels:

• configparser uses a bare object instance.
• inspect uses a class directly, without ever instantiating it.
• typing uses an instance of its own dedicated type, NoDefaultType.
• unittest.mock uses an instance of a purpose-built _SentinelObject class.

As you can see, the standard library hasn’t settled on one approach. Every module follows its own path.

In practice, you’ll find three common strategies, each with its own trade-offs:

• An instance of object gives you a unique object at the cost of a generic .__repr__() that provides no insight into the sentinel’s meaning.
• A custom class lets you write a readable .__repr__() and gives your sentinels a type you can use in a type hint, at the cost of several special methods to preserve their identity through copying and pickling.
• A single-valued Enum uses Python’s enumeration machinery for uniqueness and pickling. Its .__repr__() shows the class name, the member name, and the member’s value, even though only the name matters.

All these approaches work to some extent, but each falls short in a different way. Using an instance of object is arguably the most common option because it’s the simplest way to get a unique object. Still, it has important drawbacks that you’ll explore in the next section.

Explore Some Limitations of Sentinels in Python

PEP 661, which introduces the new sentinel built-in type in Python 3.15, names three drawbacks of the object() idiom:

1. An uninformative repr() that makes function signatures overly long and hard to read
2. No distinct type, which makes it impossible to write a clear type signature for a function that takes the sentinel as a default
3. Broken behavior after copying, because copying creates a separate instance, and comparisons using the is operator start failing

Here’s a REPL session that captures all three:

>>> _MISSING = object()
>>> _MISSING
<object object at 0x7f3006bf05d0>

>>> type(_MISSING)
<class 'object'>

>>> from copy import deepcopy
>>> deepcopy(_MISSING) is _MISSING
False

>>> import pickle
>>> pickle.loads(pickle.dumps(_MISSING)) is _MISSING
False

The memory address in the first output is what leaks into signatures and help() pages. Sphinx strips the address out when it renders a signature, but the <object object> that remains tells your readers just as little.

Calling type() shows the second drawback. The most specific type you can name for _MISSING is object, which every other Python object shares, so a type hint built on it can’t distinguish your sentinel from other objects.

The two False results are the tricky part. Neither the deep copy nor the pickle round trip preserves identity. Each returns a new object instead of the original.

Those three drawbacks apply to the object() idiom, where you deliberately create a unique marker. A different problem shows up when you repurpose a specific value instead. For example, using None, a number, or a string as a sentinel could eventually lead to a clash with real data.

The results of a missing dictionary lookup and a failed substring search can both be mistaken for legitimate data:

>>> grades = {"Jane": 90, "John": None}
>>> grades.get("John") is grades.get("Linda")
True

>>> "Pythonista!".find("z")
-1
>>> "Pythonista!"["Pythonista!".find("z")]
'!'

In the first example, a key with the value None is indistinguishable from a key that isn’t in the dictionary. This happens because the .get() method returns None by default if the target key is missing.

In the second example, -1 is a valid index, so indexing with a failed search returns the last character in the string instead of raising an error.

A dedicated class lets you customize .__repr__() and gives you a type, but its instances don’t retain their identity through a deepcopy() or pickle round trip:

>>> class _MissingType:
...     def __repr__(self):
...         return "MISSING"
...

>>> MISSING = _MissingType()
>>> MISSING
MISSING

>>> from copy import deepcopy
>>> deepcopy(MISSING) is MISSING
False

To build a class whose sentinels overcome all these limitations, you’ll need seven dunder methods. You can implement them in a _MissingType class:

class _MissingType:
    def __init__(self, name):
        self._name = name

    def __repr__(self):
        return self._name

    def __copy__(self):
        return self

    def __deepcopy__(self, memo):
        return self

    def __reduce__(self):
        return self._name

    def __eq__(self, other):
        return self is other

    def __hash__(self):
        return id(self)

Here’s a quick breakdown of what each method does:

• .__init__() stores the name, which doubles as the repr() output and the lookup key for pickling.
• .__repr__() returns the sentinel’s own name instead of a memory address.
• .__copy__() makes copy.copy() return the same object instead of a new one.
• .__deepcopy__() makes copy.deepcopy() return the same object instead of a new one.
• .__reduce__() tells pickle to look up this name as a module global when unpickling, rather than reconstruct a new instance.
• .__eq__() makes equality fall back to identity, so the sentinel compares equal only to itself.
• .__hash__() restores hashability. Defining .__eq__() makes Python drop the class’s inherited .__hash__(), so you have to redefine it explicitly.

You can create a custom class for sentinels, but implementing it correctly takes considerable work.

Finally, you can use a single-valued Enum. Enumerations survive copying and pickling, but their .__repr__() is verbose and exposes unnecessary information:

>>> import enum

>>> class MissingType(enum.Enum):
...     MISSING = "MISSING"
...

>>> MissingType.MISSING
<MissingType.MISSING: 'MISSING'>

That repr() displays the class name, the member name, and the value, even though the value exists only because Enum requires one.

Create a Sentinel Value

You can create a sentinel value by instantiating sentinel with a name as an argument. Optionally, you can provide a repr string to display instead of that name.

Here’s the signature of sentinel():

sentinel(name, /, *, repr=None)

The two parameters serve different purposes, and the slash and asterisk specify how you can pass the arguments:

• name is required, positional-only, and must be a str. It does double duty as the default repr() and as the name that pickle looks up during unpickling.
• repr is optional and keyword-only. It defaults to None, in which case the sentinel displays its name.

By convention, you assign the sentinel to a variable whose name matches the string you passed:

>>> MISSING = sentinel("MISSING")
>>> MISSING
MISSING

Cool! You’ve created your first sentinel. It prints as its own name, with no address and no angle brackets. If you give the variable and the sentinel different names, then you’ll read one name in your code and another in the output.

If the bare name might be unclear in context, then you can use the repr argument to change the displayed value:

>>> UNSET = sentinel("UNSET", repr="<unset>")
>>> UNSET
<unset>

Because repr is a keyword-only argument, passing it positionally fails. Similarly, because name is a positional-only argument, passing it as a keyword also fails:

>>> sentinel("UNSET", "<unset>")
Traceback (most recent call last):
    ...
TypeError: sentinel() takes exactly 1 positional argument (2 given)

>>> sentinel(name="UNSET")
Traceback (most recent call last):
    ...
TypeError: sentinel() takes exactly 1 positional argument (0 given)

In these examples, both errors point to the same rule. You pass the name first, as a positional argument, and supply repr by keyword.

With the sentinel() constructor covered, you can turn to how the resulting objects behave.

Explore How sentinel Instances Behave

A sentinel instance is truthy, hashable, and equal only to itself. You can use it as a dict key or a set member and compare it for identity with the is operator:

>>> MISSING = sentinel("MISSING")

>>> bool(MISSING)
True

>>> hash(MISSING)
8739378476836

>>> config = {MISSING: "unset", "timeout": 30}
>>> config[MISSING]
'unset'

>>> MISSING in {MISSING, 1, 2}
True

>>> MISSING == sentinel("MISSING")
False

Each example shows a different behavior. The sentinel is truthy, so a bare if MISSING: check is always true. That’s why you should check sentinels with is rather than with a Boolean test.

The hash() call succeeds, which is what lets the sentinel serve as a dict key and as a set member in the two examples that follow. That hash value derives from the object’s identity, so your number will differ from the one above and will change on every REPL run.

Consider the final comparison carefully. Every call to sentinel() builds a brand-new object, so two sentinels that share a name are two different objects:

>>> sentinel("STOP") is sentinel("STOP")
False

You should create your sentinels once, at the module level, and refer to them everywhere. That’s why most examples in this tutorial assign the sentinel to a variable whose name follows the naming convention for constants in Python.

All sentinel values share a common type, which has a practical consequence:

>>> A = sentinel("A")
>>> B = sentinel("B")

>>> type(A) is type(B)
True

>>> isinstance(A, sentinel)
True
>>> isinstance(B, sentinel)
True

>>> A is B
False

Both objects are instances of the same sentinel class, so an isinstance() check passes for every sentinel you’ll ever create and can’t help you distinguish the one you’re looking for. That leaves the identity check (is) as the correct way to compare them.

The shared class doesn’t get in the way of type hints, though. In a hint, you use the sentinel instance itself rather than its class, and because each instance is unique, the hint refers to that one sentinel only. You’ll see this in action in Type Hint a Sentinel Value.

Both copy() and deepcopy() preserve identity. Pickling does too, as long as the object is importable:

>>> from copy import copy, deepcopy

>>> MISSING = sentinel("MISSING")

>>> copy(MISSING) is MISSING
True

>>> deepcopy(MISSING) is MISSING
True

In each case, you get the original object instead of a new one, so the identity check still passes after copying. You’ll see what a lost identity can do to real data in Keep Identity Through copy and pickle.

Pickling is where the convention of matching name to the variable matters most. A sentinel is pickleable when pickle can find it by module and name. At the module level, that means the variable name, and at class scope, it means the qualified name.

Suppose you have the following module, which defines several sentinels:

UNSET = sentinel("UNSET")
INHERIT = sentinel("INHERITED")  # Name doesn't match the variable

class Config:
    AUTO = sentinel("Config.AUTO")
    # Some code here...
    NO_LIMIT = sentinel("NO_LIMIT")  # Forgot the qualified name

This module has four sentinels, two of which have names that don’t match their variables. The first mismatch is a typo, and the second is a missing qualified name. Both will break pickling.

Now you can try to pickle each of those four sentinels and check which of them pickle can find:

>>> import pickle
>>> from config import Config, INHERIT, UNSET

>>> pickle.loads(pickle.dumps(UNSET)) is UNSET
True
>>> pickle.loads(pickle.dumps(Config.AUTO)) is Config.AUTO
True

>>> pickle.dumps(INHERIT)
AttributeError: module 'config' has no attribute 'INHERITED'.
⮑ Did you mean '.INHERIT' instead of '.INHERITED'?

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
    ...
_pickle.PicklingError: Can't pickle INHERITED: it's not found as
⮑ config.INHERITED

>>> pickle.dumps(Config.NO_LIMIT)
AttributeError: module 'config' has no attribute 'NO_LIMIT'.
⮑ Did you mean '.Config.NO_LIMIT' instead of '.NO_LIMIT'?

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
    ...
_pickle.PicklingError: Can't pickle NO_LIMIT: it's not found as
⮑ config.NO_LIMIT

At the module level, the name has to match the variable name. At class scope, the name has to be the qualified name, which is why sentinel("Config.AUTO") works but sentinel("NO_LIMIT") doesn’t.

Finally, a sentinel that stays local to a function can’t be pickled because pickle looks up its name in the module, where a local variable isn’t available. Creating a sentinel inside a function is fine, as long as you bind the result to a module global or class attribute whose name matches.

Get a Readable Signature

Suppose your Python app keeps its database settings in a TOML file:

[db]
host = "localhost"
timeout = 30

Once tomllib has parsed that file into nested dictionaries, you want a get_setting() function that reads a dotted path like "db.timeout" in one call. If the path doesn’t exist, callers who don’t pass a default value should get a KeyError exception, and callers who do pass one should get it back:

_NO_DEFAULT = object()

def get_setting(config, path, default=_NO_DEFAULT):
    current = config
    for part in path.split("."):
        try:
            current = current[part]
        except (KeyError, TypeError):
            if default is _NO_DEFAULT:
                raise KeyError(path) from None
            return default
    return current

To try it out, load settings.toml with tomllib and look up a few paths:

>>> import tomllib
>>> from settings import get_setting

>>> with open("settings.toml", mode="rb") as file:
...     config = tomllib.load(file)
...

>>> config
{'db': {'host': 'localhost', 'timeout': 30}}

>>> get_setting(config, "db.timeout")
30
>>> get_setting(config, "db.port", default=5432)
5432
>>> get_setting(config, "db.port")
Traceback (most recent call last):
    ...
KeyError: 'db.port'

An existing path returns its value. A missing path returns the default when you pass one, and raises KeyError when you don’t.

The code works, but a problem appears when someone inspects the function’s signature with help() or inspect to learn how to call it:

>>> from settings import get_setting

>>> help(get_setting)
Help on function get_setting in module settings:

get_setting(config, path, default=<object object at 0x7fbb570bc6d0>)

>>> import inspect
>>> inspect.signature(get_setting)
<Signature (config, path, default=<object object at 0x7fbb570bc6d0>)>

In both examples, the output doesn’t tell a clear story about what default would hold or mean. The memory address is meaningless to your users, and it changes on every REPL run.

In Python 3.15, you just update the sentinel definition:

NO_DEFAULT = sentinel("NO_DEFAULT")

def get_setting(config, path, default=NO_DEFAULT):
    current = config
    for part in path.split("."):
        try:
            current = current[part]
        except (KeyError, TypeError):
            if default is NO_DEFAULT:
                raise KeyError(path) from None
            return default
    return current

You remove the leading underscore from the sentinel’s name because it’s no longer a hidden internal detail. Now, the name is part of the function’s documentation and should be readable and meaningful.

Both help() and inspect.signature() now display the sentinel’s name:

>>> from settings import get_setting

>>> help(get_setting)
Help on function get_setting in module settings:

get_setting(config, path, default=NO_DEFAULT)

>>> import inspect
>>> inspect.signature(get_setting)
<Signature (config, path, default=NO_DEFAULT)>

Great! Both tools now print NO_DEFAULT instead of an unreadable repr() that includes a memory address. Your users can see what omitting default means. Next, you’ll give the type checker useful information about that default, too.

Type Hint a Sentinel Value

Now that you have a readable signature, you can continue improving settings.py by adding type hints to get_setting(). The sentinel default is the first thing that gets in the way.

Your settings file holds strings and numbers, so get_setting() returns a str or an int. The default parameter is the problem. An object() sentinel has the type object, the broadest type hint you can give. This hint accepts any object and gives a static type checker no useful information about the intended values:

_NO_DEFAULT = object()

def get_setting(
    config: dict[str, object],
    path: str,
    default: object = _NO_DEFAULT,
) -> str | int:
    ...

Reading the hints back at runtime shows that default is annotated as object, the base of every Python type:

>>> import typing
>>> from settings import get_setting

>>> hints = typing.get_type_hints(get_setting)

>>> hints["default"]
<class 'object'>

As you can see, the hint doesn’t tell a static type checker that default can be a str, an int, or the sentinel.

Using str | int | object doesn’t help, either. A union that already includes object accepts exactly the same values as object on its own, so a static type checker treats the two hints identically, even though it keeps displaying the longer one.

An instance of sentinel supports the union operator (|) in a type hint:

NO_DEFAULT = sentinel("NO_DEFAULT")

def get_setting(
    config: dict[str, object],
    path: str,
    default: str | int | NO_DEFAULT = NO_DEFAULT,
) -> str | int:
    ...

Now, the type hint includes a specific object that Python can build and resolve:

>>> import typing
>>> from settings import get_setting

>>> hints = typing.get_type_hints(get_setting)

>>> hints["default"]
str | int | NO_DEFAULT

In this example, the type hint records that default should be a string, an integer, or NO_DEFAULT, rather than any object at all. Reading it back with typing.get_type_hints() confirms the recorded hint. Enforcing this constraint is a static type checker’s job.

You can now use your sentinel in a type hint without relying on the overly broad object. Next, you’ll make sure it keeps its identity through copy and pickle.

Keep Identity Through copy and pickle

Say that you’re building a staff directory for your company, where every employee maintains their own profile page. To keep edits small and avoid overwriting unchanged data, the edit form sends back only the fields that the employee edited.

A field that arrives as None means the employee deliberately cleared it, for example, by deleting a bio they no longer want to share publicly. A field that doesn’t arrive means the employee left it unchanged. Because None already carries real meaning, you need a separate marker for the untouched fields. You can use a sentinel for that.

Here’s an implementation that uses an object() sentinel to mark missing fields:

_MISSING = object()

def parse_patch(form):
    fields = ("name", "bio", "email")
    return {field: form.get(field, _MISSING) for field in fields}

def apply_patch(profile, patch):
    updated = dict(profile)
    for field, value in patch.items():
        if value is not _MISSING:
            updated[field] = value
    return updated

This code works. Applying the patch updates the supplied fields and preserves the rest:

>>> from profiles import apply_patch, parse_patch

>>> profile = {
...     "name": "J. Doe",
...     "bio": "Data scientist",
...     "email": "jane@example.com",
... }
>>> patch = parse_patch({"name": "jane", "bio": None})

>>> apply_patch(profile, patch)
{'name': 'jane', 'bio': None, 'email': 'jane@example.com'}

Jane updated her name and cleared her bio but left her email address unchanged, so email keeps its stored value. However, if you deep-copy patch for further computation, then the sentinel in the copy is a new object(), and the identity check fails:

>>> from copy import deepcopy
>>> from profiles import _MISSING, apply_patch, parse_patch

>>> patch = parse_patch({"name": "jane", "bio": None})

>>> deepcopy(patch)["email"] is _MISSING
False

>>> apply_patch(profile, deepcopy(patch))
{'name': 'jane', 'bio': None, 'email': <object object at 0x7ff6ae834480>}

Because the copied sentinel isn’t _MISSING, apply_patch() treats it as a real value and writes it into email. Jane’s email address is replaced with a meaningless object, and nothing warns you about it.

If you pickle the patch, then you’ll run into the same problem:

>>> import pickle
>>> from profiles import _MISSING, parse_patch

>>> patch = parse_patch({"name": "jane", "bio": None})

>>> pickle.loads(pickle.dumps(patch))["email"] is _MISSING
False

Again, the sentinel in the unpickled copy is different from _MISSING, and a corrupted email address can end up in your database without a warning or error.

A sentinel instance will survive both trips:

MISSING = sentinel("MISSING")

def parse_patch(form):
    fields = ("name", "bio", "email")
    return {field: form.get(field, MISSING) for field in fields}

def apply_patch(profile, patch):
    updated = dict(profile)
    for field, value in patch.items():
        if value is not MISSING:
            updated[field] = value
    return updated

The sentinel now retains its identity through copying and pickling, so both identity checks pass, and applying a copied patch leaves the email address untouched:

>>> import pickle
>>> from copy import deepcopy
>>> from profiles import MISSING, apply_patch, parse_patch

>>> profile = {
...     "name": "J. Doe",
...     "bio": "Data scientist",
...     "email": "jane@example.com",
... }
>>> patch = parse_patch({"name": "jane", "bio": None})

>>> deepcopy(patch)["email"] is MISSING
True

>>> pickle.loads(pickle.dumps(patch))["email"] is MISSING
True

>>> apply_patch(profile, deepcopy(patch))
{'name': 'jane', 'bio': None, 'email': 'jane@example.com'}

Because the sentinel keeps its identity, you don’t risk silently corrupting your data.

Stop a Loop Without Collisions

To see how a sentinel can collide with real data, say that you have a producer thread that hands you one word at a time for individual processing. You don’t have control over the words that come in, so any string you pick as the stream terminator, or sentinel, can also arrive as real data.

Suppose you and the producer agree on the string "done" as the sentinel. The producer sends its words one by one and then appends the sentinel to close the stream. When you read words from another thread, you can’t tell on your own when the producer has finished, so you need that explicit end marker. To keep the example short, a generator stands in for the producer thread:

>>> STOP = "done"

>>> def producer():
...     words = ["ready", "done", "pending"]  # Simulate produced words
...     for word in words:
...         yield word
...     yield STOP
...

>>> words_stream = producer()

>>> for word in words_stream:
...     if word == STOP:
...         break
...     print(f"Processing '{word}'...")
...
Processing 'ready'...

In this example, you get to process only the first word. The loop stops at the second word, "done", even though that word is legitimate data. Your sentinel collides with a value you need to process.

Because the new sentinel type returns a unique object, you can use it to mark the end of a stream without worrying about data collisions. Note that producer() looks up STOP when it runs, not when you define it. So if you rebind STOP to a sentinel and create a new stream, the stream ends with the sentinel instead of the string:

>>> STOP = sentinel("STOP")

>>> words_stream = producer()

>>> for word in words_stream:
...     if word is STOP:
...         break
...     print(f"Processing '{word}'...")
...
Processing 'ready'...
Processing 'done'...
Processing 'pending'...

Now, "done" flows through as ordinary data, and the loop ends only when the actual sentinel arrives. The comparison changed too. You need to check a string sentinel with the equality operator (==) because equal strings aren’t guaranteed to be the same object. A sentinel instance is unique, so is is the right check, as you saw earlier.

Switch the terminator between the two sentinel definitions and watch where the consumer loop stops:

The string terminator costs you two of the three words, while the sentinel lets every one of them through.