To restrict a variable's allowed values to a fixed set of literal strings, enabling static type checkers to reject invalid values and providing IDE autocompletion for those exact strings.

Communicates to type checkers and human readers that a variable can only take one of the three specified string literals.

Used when a variable should only accept a known set of string values, such as configuration options, status flags, mode selectors, or any domain‑limited set of strings.

Appears in variable annotations, function parameter or return type annotations, class attributes, and any location where Python type hints are accepted.

typing.Literal[<literal1>, <literal2>, ...] where each <literal> is a string, integer, boolean, or enum literal.

typing.Literal, square brackets, comma‑separated literal values.

items: comma‑separated literals (e.g., string literals) that define the allowed values.

• typing import
• variable annotations
• function signatures
• return types
• MyPy
• pyright
• IDE autocomplete
• Enum
• TypedDict.

• Union of literal types (e.g.
• Union[Literal['red']
• Literal['green']
• Literal['blue']])
• Enum class
• or a plain str with runtime validation.

Forgetting to import typing.Literal, causing a NameError; using variable names instead of quoted literals inside Literal, leading to a type error; omitting quotes around string literals, resulting in a NameError; using non‑literal expressions (e.g., variables) inside Literal, which static checkers reject; forgetting to use typing_extensions.Literal for Python versions <3.8, causing import errors.

typing.Union of literals – expresses the same set but is more verbose; typing.LiteralString – restricts to any string literal rather than a fixed set; enum.Enum – provides a class with attributes and methods, suitable when values need behavior; typing.TypedDict – describes a dictionary with specific keys, not a single value.

Coming from Java: may confuse Literal with enum classes, expecting methods on the literals → remember Literal values are plain strings with no methods; use Enum if behavior is needed. Coming from TypeScript: may assume structural similarity, but Python's Literal is nominal and requires an explicit import → import typing.Literal. Coming from C: may try to use macros or #define constants, which static type checkers do not recognize → use Literal or Enum for type safety.

• typing.Literal
• typing.Union
• typing.TypedDict
• enum.Enum
• typing.NewType

Avoid using Literal for large or dynamic sets of strings; prefer Enum or configuration files when the set may change. Performance impact is negligible because Literal is a type‑only construct with no runtime overhead. Boundary condition: Literal only accepts literal values known at static analysis time; variables or function calls cannot appear inside Literal, even if they hold constant values.

Using Literal enables static type checkers to catch invalid string values early, prevents runtime errors from invalid configuration values, and improves IDE autocomplete and refactoring safety for limited‑option strings.

Think of Literal as a whitelist bouncer at a club: only the exact names on the list are allowed past the velvet rope.

Literal is erased at runtime; it exists solely for static type checking. For Python versions prior to 3.8, use typing_extensions.Literal.

When the set of allowed strings grows or requires associated behavior, consider replacing Literal with an Enum or a TypedDict for richer structure.