Nullable lookup results
A lookup may fail without raising an exception and returns None when no matching value exists.
Python · Type Alias
Optional
Optional[X] describes a value that may be either X or None. In modern Python, X | None is the equivalent spelling; Optional does not merely mean that an argument has a default.
- Since
- 3.5
How it works
Optional[X] annotates a value that may be an X or None. It describes whether None is an allowed value, not whether an argument may be omitted; in modern Python, X | None expresses the same type.
Syntax
Optional[X]Parameters
| Name | Type | Description |
|---|---|---|
X | type | X is the type that may be present instead of None. |
Returns
A type expression equivalent to Union[X, None], indicating that a value may be X or None.
Key points
- Optional[X] permits either X or None; modern Python can spell it as X | None.
- Use Optional when None is explicitly part of the permitted values.
- Optional is mainly information for static analysis, not a runtime restriction.
- Type checkers, IDEs, and linters can use Optional annotations to analyze code.
Common mistakes
- An argument with a default is not automatically Optional; use Optional when None is an accepted value.
- A default value alone does not require Optional.
Example: A nullable return type
from typing import Optional
def lookup_user(user_id: int) -> Optional[str]:
if user_id == 1:
return "Ada"
return None
print(lookup_user(1))
print(lookup_user(2))The return annotation allows either a string or None.
When to use it
Nullable inputs
An API accepts an explicit null-like value alongside a concrete domain type.
Cross-version annotations
A codebase supports Python versions before 3.10 and needs the older typing spelling.
Interview questions
QWhat does Optional[X] mean?
Optional[X] means X or None, and it is equivalent to X | None or Union[X, None]. It is useful when a type checker should account for a possible None value.
Follow-up: When can the modern spelling be used? Python 3.10 added X | None as an alternative spelling.
QDoes Optional mean a parameter may be omitted?
No. Optional describes the set of permitted values, whereas an optional argument can simply mean an argument has a default. A parameter with a default does not need Optional unless None is also valid.
Follow-up: How would you annotate a parameter that has a default of 0 but must remain an integer? Use int, not Optional[int].
QWho enforces Optional annotations?
The annotation is not enforced by the Python runtime. Static type checkers, IDEs, and linters can use it to detect code that fails to handle the None case.
Follow-up: What should code do after receiving Optional[T]? Narrow or check the value before using operations that require T.
Related
UnionAnyTypeVartype annotations