Null Object & Sentinels

Q: Is object() the standard sentinel?

Common in stdlib patterns (getattr(obj, name, default) uses its own sentinel internally). Public APIs often prefer named enums for clarity.

Q: How do type checkers handle sentinels?

Use overload on functions where return type depends on whether default was provided, or union T | Literal[_MISSING].

Q: Can Pydantic use sentinels?

Use model_fields_set to detect unset fields instead of custom sentinels - Pydantic v2 tracks what was provided.

Q: Default mutable arguments?

Never def f(items=[]). Use None and items = [] if items is None else items, or a sentinel plus factory.

Q: Sentinel vs Ellipsis (...)?

... appears in slicing and stub files. Rarely use as runtime sentinel - object() or Enum is clearer.

Q: How do I test sentinel paths?

Assert behavior when param omitted, when None passed, and when real value passed - three distinct cases.

Q: Does functools.lru_cache need sentinels?

Distinguish "not cached" from cached None using a private sentinel in wrapper implementations - same pattern.

None often means both "missing" and "empty value," which causes bugs. Sentinels are unique marker objects for "not provided." Null objects implement the same interface as real collaborators but do nothing - callers skip if obj is not None checks.

Recipe

Quick-reference recipe card - copy-paste ready.

from typing import Any
 
MISSING: Any = object()
 
def lookup(key: str, default=MISSING):
    try:
        return cache[key]
    except KeyError:
        if default is MISSING:
            raise
        return default

When to reach for this:

Distinguish missing from None - optional fields where None is valid data
Default mutable args - never use [] or {}; use None or a sentinel
Null object - no-op logger, mailer, or cache for disabled features
API boundaries - default=MISSING vs default=None semantics
Enum.NONE - named sentinel in typed APIs

Working Example

A sentinel distinguishes unset config from explicit None; a null logger skips I/O.

from dataclasses import dataclass
from typing import Any, Protocol
 
UNSET: Any = object()
 
@dataclass
class Config:
    timeout: float | None | object = UNSET
 
def resolve_timeout(cfg: Config, fallback: float = 30.0) -> float:
    if cfg.timeout is UNSET:
        return fallback
    if cfg.timeout is None:
        raise ValueError("timeout explicitly disabled")
    return float(cfg.timeout)
 
class Logger(Protocol):
    def info(self, msg: str) -> None: ...
 
@dataclass
class NullLogger:
    def info(self, msg: str) -> None:
        pass
 
@dataclass
class StdoutLogger:
    def info(self, msg: str) -> None:
        print(msg)
 
def run_job(logger: Logger | None = None) -> None:
    log = logger if logger is not None else NullLogger()
    log.info("starting")
    log.info("done")
 
print(resolve_timeout(Config()))           # 30.0
print(resolve_timeout(Config(timeout=5.0)))  # 5.0
run_job()  # silent
run_job(StdoutLogger())

What this demonstrates:

UNSET is not equal to any user value, including None
Explicit None can mean "disabled" with different behavior than unset
NullLogger implements the interface with no-ops
Optional dependency defaults to null object at runtime

Deep Dive

How It Works

object() creates a unique identity; is checks are O(1) and unambiguous
enum.Enum members can serve as named sentinels in public APIs
Null object pattern: substitute a do-nothing implementation instead of branching
dataclasses.MISSING (3.13+) documents field state in some APIs
Type checkers need Literal or overloads when sentinels affect return types

Sentinel vs None vs Optional

Value	Meaning
`UNSET`	Caller did not pass the argument
`None`	Caller passed empty/absent semantic value
`Optional[T]`	Value may legitimately be `None`

Python Notes

from enum import auto, Enum
 
class _Sentinel(Enum):
    MISSING = auto()
 
MISSING = _Sentinel.MISSING  # named repr in debug output

Gotchas

Sentinel leaks in serialized data - JSON cannot represent object(). Fix: convert to null or omit key at API boundary.
Equality checks with == - sentinels must use is, not ==. Fix: document and lint for is UNSET.
Overusing null objects - masking real bugs when dependency should be required. Fix: require non-null deps in production wiring.
Mutable sentinel singletons - never attach state to the sentinel object. Fix: use immutable enum members.
Confusing default=None and default=UNSET - API docs must state semantics clearly. Fix: name parameters timeout_or_unset.

Alternatives

Alternative	Use When	Don't Use When
`Optional` only	`None` is the only missing semantics	Missing vs empty must differ
`**kwargs` only	Truly optional extension fields	Core params need positional clarity
`NotRequired` TypedDict	JSON-like partial dicts	Function parameters
Raise on missing	Required values	Optional with three states

FAQs

Why not use None for missing and missing only?

When None is valid data (nullable database column), you need a third state for "argument not passed."

Is object() the standard sentinel?

Common in stdlib patterns (getattr(obj, name, default) uses its own sentinel internally). Public APIs often prefer named enums for clarity.

What is a null object?

A class implementing the same interface as real services but performing no work - avoids None checks at call sites.

How do type checkers handle sentinels?

Use overload on functions where return type depends on whether default was provided, or union T | Literal[_MISSING].

Can Pydantic use sentinels?

Use model_fields_set to detect unset fields instead of custom sentinels - Pydantic v2 tracks what was provided.

Default mutable arguments?

Never def f(items=[]). Use None and items = [] if items is None else items, or a sentinel plus factory.

Sentinel vs Ellipsis (...)?

... appears in slicing and stub files. Rarely use as runtime sentinel - object() or Enum is clearer.

How do I test sentinel paths?

Assert behavior when param omitted, when None passed, and when real value passed - three distinct cases.

Null object vs optional dependency?

Null object always callable; optional dependency may skip feature entirely. Pick based on call-site branching cost.

Does functools.lru_cache need sentinels?

Distinguish "not cached" from cached None using a private sentinel in wrapper implementations - same pattern.

EAFP vs LBYL - handling missing keys
Dependency Injection in Python - null object as default dep
Factory & Builder Patterns - optional fields in builders
Pythonic Patterns Basics - section overview

Python Language Reference - Formal description of Python syntax and core semantics.
Real Python - In-depth tutorials, courses, and practical guides.
Stack Overflow – Python Tag - Q&A for Python programming problems.
Fluent Python (2nd Edition, O'Reilly) - Same book on O'Reilly.
The Quick Python Book (4th Edition) - Concise Python overview (Naomi Ceder).

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.

Recipe

Quick-reference recipe card - copy-paste ready.

from typing import Any
 
MISSING: Any = object()
 
def lookup(key: str, default=MISSING):
    try:
        return cache[key]
    except KeyError:
        if default is MISSING:
            raise
        return default

When to reach for this:

Distinguish missing from None - optional fields where None is valid data
Default mutable args - never use [] or {}; use None or a sentinel
Null object - no-op logger, mailer, or cache for disabled features
API boundaries - default=MISSING vs default=None semantics
Enum.NONE - named sentinel in typed APIs

Working Example

A sentinel distinguishes unset config from explicit None; a null logger skips I/O.

from dataclasses import dataclass
from typing import Any, Protocol
 
UNSET: Any = object()
 
@dataclass
class Config:
    timeout: float | None | object = UNSET
 
def resolve_timeout(cfg: Config, fallback: float = 30.0) -> float:
    if cfg.timeout is UNSET:
        return fallback
    if cfg.timeout is None:
        raise ValueError("timeout explicitly disabled")
    return float(cfg.timeout)
 
class Logger(Protocol):
    def info(self, msg: str) -> None: ...
 
@dataclass
class NullLogger:
    def info(self, msg: str) -> None:
        pass
 
@dataclass
class StdoutLogger:
    def info(self, msg: str) -> None:
        print(msg)
 
def run_job(logger: Logger | None = None) -> None:
    log = logger if logger is not None else NullLogger()
    log.info("starting")
    log.info("done")
 
print(resolve_timeout(Config()))           # 30.0
print(resolve_timeout(Config(timeout=5.0)))  # 5.0
run_job()  # silent
run_job(StdoutLogger())

What this demonstrates:

UNSET is not equal to any user value, including None
Explicit None can mean "disabled" with different behavior than unset
NullLogger implements the interface with no-ops
Optional dependency defaults to null object at runtime

Deep Dive

How It Works

object() creates a unique identity; is checks are O(1) and unambiguous
enum.Enum members can serve as named sentinels in public APIs
Null object pattern: substitute a do-nothing implementation instead of branching
dataclasses.MISSING (3.13+) documents field state in some APIs
Type checkers need Literal or overloads when sentinels affect return types

Sentinel vs None vs Optional

Value	Meaning
`UNSET`	Caller did not pass the argument
`None`	Caller passed empty/absent semantic value
`Optional[T]`	Value may legitimately be `None`

Python Notes

from enum import auto, Enum
 
class _Sentinel(Enum):
    MISSING = auto()
 
MISSING = _Sentinel.MISSING  # named repr in debug output

Gotchas

Sentinel leaks in serialized data - JSON cannot represent object(). Fix: convert to null or omit key at API boundary.
Equality checks with == - sentinels must use is, not ==. Fix: document and lint for is UNSET.
Overusing null objects - masking real bugs when dependency should be required. Fix: require non-null deps in production wiring.
Mutable sentinel singletons - never attach state to the sentinel object. Fix: use immutable enum members.
Confusing default=None and default=UNSET - API docs must state semantics clearly. Fix: name parameters timeout_or_unset.

Alternatives

Alternative	Use When	Don't Use When
`Optional` only	`None` is the only missing semantics	Missing vs empty must differ
`**kwargs` only	Truly optional extension fields	Core params need positional clarity
`NotRequired` TypedDict	JSON-like partial dicts	Function parameters
Raise on missing	Required values	Optional with three states

FAQs

Why not use None for missing and missing only?

When None is valid data (nullable database column), you need a third state for "argument not passed."

Is object() the standard sentinel?

Common in stdlib patterns (getattr(obj, name, default) uses its own sentinel internally). Public APIs often prefer named enums for clarity.

What is a null object?

A class implementing the same interface as real services but performing no work - avoids None checks at call sites.

How do type checkers handle sentinels?

Use overload on functions where return type depends on whether default was provided, or union T | Literal[_MISSING].

Can Pydantic use sentinels?

Use model_fields_set to detect unset fields instead of custom sentinels - Pydantic v2 tracks what was provided.

Default mutable arguments?

Never def f(items=[]). Use None and items = [] if items is None else items, or a sentinel plus factory.

Sentinel vs Ellipsis (...)?

... appears in slicing and stub files. Rarely use as runtime sentinel - object() or Enum is clearer.

How do I test sentinel paths?

Assert behavior when param omitted, when None passed, and when real value passed - three distinct cases.

Null object vs optional dependency?

Null object always callable; optional dependency may skip feature entirely. Pick based on call-site branching cost.

Does functools.lru_cache need sentinels?

Distinguish "not cached" from cached None using a private sentinel in wrapper implementations - same pattern.

EAFP vs LBYL - handling missing keys
Dependency Injection in Python - null object as default dep
Factory & Builder Patterns - optional fields in builders
Pythonic Patterns Basics - section overview

Python Language Reference - Formal description of Python syntax and core semantics.
Real Python - In-depth tutorials, courses, and practical guides.
Stack Overflow – Python Tag - Q&A for Python programming problems.
Fluent Python (2nd Edition, O'Reilly) - Same book on O'Reilly.
The Quick Python Book (4th Edition) - Concise Python overview (Naomi Ceder).

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.

Null Object & Sentinels

Search Documentation

Null Object & Sentinels