How does Python's `int | str` union spelling differ from `typing.Union[int, str]`?

### One type, two spellings `typing.Union[int, str]` and `int | str` denote the same type. Every checker treats them identically, and `Optional[X]` is just the same union with `None` as one member: `Optional[int]`, `Union[int, None]` and `int | None` are three ways of writing one thing. ### What PEP 604 added in Python 3.10 The operator form is the newer spelling and it brought three practical wins: 1. **No import.** `def load(shard: str, retries: int | None) -> bytes | None:` needs nothing from `typing`. 2. **It reads better nested.** `dict[str, list[int] | None]` against `Dict[str, Optional[List[int]]]`. 3. **It works at runtime in `isinstance` and `issubclass`.** `isinstance(value, int | str)` is a legal check from 3.10 onward, so the same expression can serve as both an annotation and a runtime test. Before 3.10 the operator raised `TypeError` when the annotation was evaluated, which is why code targeting 3.9 and earlier either used `typing.Union`, quoted the annotation as a string, or turned on the `__future__` import that stores annotations unevaluated. ### Normalization: unions are sets, not sequences Both spellings normalize the members, and the rules are worth knowing because they explain surprising `repr` output and equality results: - **Nested unions flatten.** `Union[int, Union[str, int]]` is `int | str`. - **Duplicates collapse.** Writing the same member twice changes nothing. - **A one-member union collapses to the member.** `Union[int]` is simply `int`, not a union at all. - **Order does not affect equality.** `int | str == str | int` is `True`. The order is preserved for display, but two unions with the same members are the same type. - **`Optional` folds in.** `Optional[Optional[str]]` is `str | None`, and `Optional[int | str]` is `int | str | None`. A consequence: you cannot rely on member order for dispatch, and you cannot build a "union with a duplicate" to carry extra meaning. ### Where the operator form does not reach - **Both operands must be types.** `int | str` works because both sides are classes; an expression like a string literal on the left is a `TypeError`, since `|` on `str` values is simply not defined. - **`isinstance` still refuses parameterized generics.** `isinstance(rows, list[int] | None)` raises `TypeError: isinstance() argument 2 cannot be a parameterized generic`. The check has no way to inspect the element types without walking the object. Erase the parameter — `isinstance(rows, list | None)` — and check elements separately if you truly need to. - **Some annotations are strings anyway.** A union written inside a quoted annotation is not evaluated where it appears, so it does not need the operator to exist at that moment. ### `Optional` is not deprecated `typing.Optional` and `typing.Union` remain part of the standard library and are not scheduled for removal; enormous amounts of code use them and reading that code is part of the job. The guidance is about new code and consistency: pick one spelling per codebase, and on any currently supported Python that spelling should be the operator form. ### The 3.14 wrinkle Through 3.13 the two spellings produced different kinds of runtime object that nonetheless compared equal, which occasionally surprised code that inspected annotations. In 3.14 they were unified: `typing.Union[int, str]` and `int | str` now produce the same kind of union object, so the last observable difference between the spellings is gone. For annotation purposes nothing changed — they always meant the same type. ### Choosing members deliberately The mechanical question ("which spelling?") is easy; the design question is which members belong in the union at all. A union of two unrelated types often means the function is doing two jobs, and a union that grows a member per release is a signature drifting toward `Any`. Unions earn their place when the alternatives are genuinely equivalent to the caller — a value or its absence, a parsed result or a raw fallback — and each member is something the caller can act on. ### What an interviewer is listening for That you state the equivalence flatly rather than hedging; that you attach the operator form to Python 3.10 and PEP 604; that you know unions flatten, deduplicate and ignore order; and that you can name at least one place the runtime form does not work, such as `isinstance` with a parameterized generic.