When is None a bad sentinel for an omitted Python argument, and what do you use instead?

### Where `None` runs out The `None` default works because `None` is immutable, identity-testable and universally understood as "nothing here". It stops working the moment `None` becomes a **legal value for that parameter**, because then a function cannot distinguish two different caller intents: ```python def sync(records, timeout=None): if timeout is None: timeout = DEFAULT_TIMEOUT # was the caller silent, or did they say "no timeout"? ``` If `timeout=None` is supposed to mean *block forever*, the omitted case and the explicit case collapse into one branch. The parameter now has three states — omitted, explicitly `None`, an actual value — and a two-state placeholder cannot represent three states. The same shape shows up whenever `None` is meaningful: a nullable field being written to a store, `parent=None` for a root node, `session=None` meaning "run without a session". ### The sentinel object The idiom is a unique, private, module-level object compared by identity: ```python _MISSING = object() def sync(records, timeout=_MISSING): if timeout is _MISSING: timeout = DEFAULT_TIMEOUT ... ``` `object()` is the smallest thing in the language guaranteed to be unequal (and non-identical) to anything a caller could construct or import by accident. It is immutable in the sense that matters — it has no state to share — so using it as a default value is safe under the def-time evaluation rule that makes `[]` dangerous. Test it with `is`, never `==`: identity is the whole point, and `==` invites a user-defined `__eq__` to answer for you. Three refinements separate a considered design from a copied snippet: **Give it a `__repr__`.** A bare `object()` renders as `<object object at 0x104e2b160>` in `help()` output, in a traceback and in generated documentation. A one-class sentinel reads properly: ```python class _MissingType: def __repr__(self): return "<missing>" MISSING = _MissingType() ``` **Decide whether it is public.** If callers ever need to pass the sentinel explicitly — to say "restore the default" on a partial-update API — it is part of your public surface and needs a name without a leading underscore, documentation, and a stability promise. If not, keep it private; an accidentally-exported sentinel becomes a thing other modules import and compare against, and you can never change it. The standard library shows both instincts: `dataclasses.MISSING` and `inspect.Parameter.empty` are public because their APIs require callers to see them. **Never make the sentinel mutable.** A sentinel that is an empty list or dict re-creates the exact bug you were avoiding: shared state on the function object, plus a value a caller could equal by accident. ### The alternative: `**kwargs` membership You can also detect omission precisely by not declaring the parameter at all: ```python def sync(records, **options): timeout = options["timeout"] if "timeout" in options else DEFAULT_TIMEOUT ``` This is exact and needs no sentinel, but it erases the parameter from the signature: no introspection, no editor completion, no error on a misspelled keyword, and a typo becomes a silently ignored option. Use it for genuine pass-through layers; prefer the sentinel for a named parameter you want documented. ### A scenario worth having lived through An inventory sync between two systems had `def sync(records, session=None)`, where `None` meant "open your own session". A later change wanted "run without a session at all" for a dry-run mode, and the quickest-looking fix was to move a shared session into the signature — `session=make_session()` — which opened a connection at import time that no code path ever closed; the socket outlived every request and the dry-run flag still could not be expressed. The correct fix was a sentinel: `session=_MISSING` means "make me one", `session=None` means "no session", and any session object means "use this one". On an 11-person team the value of that change is not cleverness but legibility — three intents, three visibly distinct values, and no resource created by the act of importing a module. ### What to say Lead with the diagnosis: `None` fails when `None` is data. Then the mechanism: a private module-level `object()` (or a tiny class with a `__repr__`), compared with `is`, safe as a default precisely because it has no mutable state. Then the design judgement: whether the sentinel is public, and the `**kwargs` alternative with its cost. Noting that the standard library has API-specific sentinels but no general-purpose factory — you write your own — shows you know the current state of the language rather than assuming a helper exists.