How does defining _missing_ on an Enum change a failed value lookup?

### The hook `_missing_` is a classmethod you define on an `enum.Enum` subclass. The class calls it from the **call syntax only** — `PickStatus(value)` — and only after the value-to-member mapping has already failed to find a member. It receives the value that was passed in, and its return value decides what the caller sees. The contract is narrow, and it is enforced: * **Return a member of this enum** and the lookup succeeds; the caller gets that member and never learns a fallback happened. * **Return `None`** and the original `ValueError` is raised, with the usual `'lost-in-transit' is not a valid PickStatus` message. `None` means "I have nothing", not "return `None` to the caller". * **Return anything else** — a raw string, an int, a member of a different enum — and you get a `TypeError` reading `error in PickStatus._missing_: returned ... instead of None or a valid member`. This is a common bug: returning the *value* you normalised instead of the member. * **Raise inside `_missing_`** and your exception propagates to the caller, with the `ValueError` attached as its context. Useful for a deliberate domain error; unpleasant when it is accidental, because the traceback now points into the enum rather than the call site. Because it is a `classmethod`, `cls` is the enum class, which is how a `_missing_` inherited from a mixin base can serve several enums. ### A worked example A warehouse pick-list builder ingests status codes from a legacy feed that spells them in upper case, sometimes with stray whitespace, while the enum stores lower-case values: ```python import enum class PickStatus(enum.Enum): QUEUED = "queued" PICKED = "picked" SHORT = "short" @classmethod def _missing_(cls, value): if isinstance(value, str): return cls.__members__.get(value.strip().upper()) return None assert PickStatus(" Picked ") is PickStatus.PICKED ``` Every call site that already writes `PickStatus(code)` now tolerates the feed's spelling, with no change at the call sites and no wrapper function to remember. Note what the fallback does here: it normalises and then resolves through `__members__`, the name mapping — so it deliberately accepts a *name* on the value door. That is a choice, and it is worth a comment in the code, because it makes the two lookups less distinct than the language made them. ### What it does not do `_missing_` backs the value door only. `PickStatus['BOGUS']` still raises `KeyError` without ever calling it, attribute access still raises `AttributeError`, and a membership test still just answers `True` or `False`. If you want lenient name lookup, write it against `__members__`. It is also not the alias mechanism. An alias is created once, when the class body runs, by repeating a value; `_missing_` runs at lookup time and creates nothing by default. (A member it hands back should already exist — the standard library's flag enums use `_missing_` to build cached composite pseudo-members, which is an advanced pattern: if you invent objects there without caching them, `is` comparisons and pickling stop behaving like an enum.) ### When it is the right tool, and when it is not `_missing_` is at its best for a **stable, total normalisation**: case folding, whitespace, a fixed table of retired codes that map onto current members. The rule is small, it is the same everywhere, and hiding it inside the type is genuinely better than repeating it at fifty call sites. It is at its worst as a **catch-all**. A `_missing_` that returns an `UNKNOWN` member for anything it does not recognise deletes your input validation: malformed codes stop raising, flow into the pick-list, and surface much later as a state nothing knows how to handle. If unknown input must be tolerated, make that visible at the call site — a named classmethod parser that takes an explicit default, or an explicit `try`/`except ValueError` — so a reader can see leniency being chosen rather than inheriting it from the type. Three more operational points. It sits on the miss path of every lookup, including lookups deep in library code you did not write, so it must be cheap and side-effect free — no I/O, no logging that can throw, no network. It must be deterministic, or the same input will resolve differently in two processes. And because it changes what the constructor accepts, it widens the type's contract: the set of values that produce a member is no longer the set written in the class body, so document it, and test both the accepted-alias path and the still-rejected path — the second test is the one that catches a catch-all creeping in later.