When would you expose a parameter as typing.Literal[...] rather than as an enum.Enum in a public API?

## Two ways to spell a closed set Both constructs answer the same question — "this parameter has three legal values" — and a checker can reason about either. The decision is an API-design one, and it turns on who pays. ```python Mode = Literal["read", "write"] # callers pass a bare string class Phase(StrEnum): # callers import and pass Phase.ALIGN ALIGN = "align" CALL = "call" ``` ## What a literal union gives you **Zero import cost for callers.** The parameter accepts data the caller already has. A genome- annotation pipeline whose stage names arrive from a YAML config, a CLI argument or a job payload holds strings; with a literal union those strings flow straight into the call. With an enum, every one of those boundaries needs a conversion. **A self-documenting signature.** `mode: Literal["read", "write", "append"]` states the whole domain in the place a reader is already looking, with no jump to a definition. **Nothing to version.** There is no class to import, so there is no import cycle, no question of which module owns it, and no mismatch when two copies of a package end up loaded. **Cheap introspection.** `typing.get_args` on the alias recovers the tuple of values, which is enough to generate CLI choices or a validator from the same declaration. ## What an enum gives you **One canonical definition.** Rename a value in one place instead of grepping for a string repeated across a dozen signatures and a hundred call sites. This is the argument that grows with the codebase. **Runtime validation.** Calling the enum with a value that is not a member raises `ValueError`. A literal union has no runtime existence at all, so an unvalidated string from JSON sails past every annotation in the process. **Somewhere to attach things.** Members carry methods, properties and metadata: a per-mode timeout, a default budget, a display label. A literal union has nowhere to hang any of that, and the logic ends up as a dict keyed by the string, defined somewhere else, easy to leave incomplete. **Discoverability.** Typing `Phase.` in an editor lists the options; discovering the legal strings requires reading the signature. ## The cost of the enum, honestly Callers must import your class, which couples them to your module layout. Every serialisation boundary needs conversion in both directions — `StrEnum` (3.11) makes members usable directly as strings and eases the outbound half, but you still need a lookup inbound. And identity comparisons break in the awkward cases: two copies of a module loaded under different names, or a value that crossed a process boundary and came back, produce members that are not the same object. ## The shape that usually wins Take the union at the edge and the enum inside: ```python def run_stage(phase: Phase | Literal["align", "call"]) -> None: phase = Phase(phase) # one validating conversion at the boundary ... ``` Callers who already have the enum pass it; callers holding a config string pass that; the body deals with exactly one type. The conversion is the runtime validation the annotation could never provide. ## Rules of thumb Reach for a **literal union** when the set is small and stable, the values are already strings in the surrounding system, nothing needs to hang off them, and the parameter sits at an outer boundary where imports are a tax on your users. Two or three modes on a handful of functions is exactly this case. Reach for an **enum** when the set is used in many places, is likely to be renamed or extended, needs per-member behaviour or metadata, or must be validated at runtime because the value comes from outside the type system. Anything that becomes a domain concept in its own right — a state, a phase, a severity — has outgrown a literal union. The judgement an interviewer is listening for is that neither choice provides runtime safety by itself: the literal union provides none, and the enum provides it only at the moment you call the class on an incoming value. Wherever untyped data enters, one explicit conversion or check has to exist, and the type declaration merely tells you where to put it. ## Generating the rest from the declaration Whichever you pick, the declaration should be the single source for everything derived from it. `typing.get_args` on a named literal alias yields the tuple of legal values, so CLI choices, documentation tables and a validation helper can be generated from the same alias the checker reads — which removes the most common decay mode, where the annotation gains a value and the hand-written validator does not. An enum gives you the same thing by iterating the class, plus a natural place to record what each value *means*. The failure to avoid is a third copy: an annotation listing three values, a validator listing four, and a documentation string listing two. That divergence is what actually bites in production, and it is independent of which construct you chose — so whichever you pick, derive rather than repeat.