Why does set.union accept a list argument when the | operator does not?

## Two spellings, one algebra, different contracts Python gives every set-algebra operation two spellings: | operation | operator | method | |---|---|---| | union | `a \| b` | `a.union(b, ...)` | | intersection | `a & b` | `a.intersection(b, ...)` | | difference | `a - b` | `a.difference(b, ...)` | | symmetric difference | `a ^ b` | `a.symmetric_difference(b)` | plus the in-place pairs `|=` / `update`, `&=` / `intersection_update`, `-=` / `difference_update`, `^=` / `symmetric_difference_update`. They compute identical results, but their input contracts differ in two ways that matter in real code. ## Difference one: operand types The operator forms require both operands to be `set` or `frozenset`. Python evaluates `a | b` by calling `type(a).__or__(a, b)`; the set implementation inspects `b`, sees a non-set, and returns `NotImplemented`. The interpreter then tries the reflected `type(b).__ror__`, and when a plain `list` offers none either, it raises: ``` TypeError: unsupported operand type(s) for |: 'set' and 'list' ``` The method forms take any iterable and iterate it. `{1, 2}.union([2, 3])` is fine, and so is `.union(range(5))`, a generator, a `str` (which contributes its characters), or a `dict` (which contributes its keys - a genuine trap when you meant the values). The asymmetry is a deliberate design choice, not an oversight. Between two sets, `|` reads as algebra. Between a set and a sequence it is almost always a mistake - someone forgot a `set(...)` call - and the language would rather fail at that line than silently produce a set from data that was never deduplicated on purpose. ## Difference two: arity `union`, `intersection` and `difference` accept any number of arguments: `a.difference(b, c, d)` removes everything in `b`, `c` or `d` in one pass, with no intermediate sets. `symmetric_difference` and `symmetric_difference_update` take exactly one argument, because the operation is not naturally n-ary - chained `^` is associative but means something unintuitive (elements appearing an odd number of times), so the API refuses to encourage it. `update` also accepts several iterables: `s.update(rows, extras, {'k': 'v'})`. ## The in-place forms `s |= other` is not merely `s = s | other`. The augmented form calls `set.__ior__`, which mutates `s` in place, so every other name bound to that same set object sees the change. `s = s | other` builds a new set and rebinds only the local name. When a set is shared - a module-level registry, an attribute on an object someone else holds - that distinction decides whether their view updates. And `|=` inherits the operator's strictness: `s |= [3]` raises `TypeError`, while `s.update([3])` works. ## Result types when set and frozenset mix The operators accept a `frozenset` on either side, and the result takes the type of the left operand: `frozenset({1}) | {2}` is a `frozenset`, `{1} | frozenset({2})` is a `set`. The method forms follow the receiver: `frozenset({1}).union([2])` is a `frozenset`. If a function must return something immutable, call the method on the frozenset, or wrap the result explicitly rather than relying on operand order. ## Which spelling to write With two sets in hand, the operators win on readability - `wanted & available` reads as a sentence and the precedence is the familiar one (`&` binds tighter than `^`, which binds tighter than `|`; use parentheses when mixing). Reach for the method form when the right-hand side is not a set and materialising it would be wasteful, when you have several right-hand sides, or when you want a reader to see the type-flexibility on purpose. One performance note about the difference between them: `a.union(big_generator)` consumes the generator lazily into a new set, whereas `a | set(big_generator)` builds an intermediate set first. On large inputs the method form is the leaner one. ## The mistake this question is really probing Candidates who have only ever written `a | b` between two literals are surprised that the same line fails when `b` arrives from a function returning a list, and they often conclude that sets 'do not work with lists'. The right mental model is narrower: the operators are typed strictly, the methods are typed loosely, and the fix is either `set(b)` or `a.union(b)` - chosen deliberately, not by trial and error.