How does `tuple[int, ...]` differ from `tuple[int, str]` in a signature?

### Tuples are the one container with two shapes Every other builtin container is uniform: a `list[int]` is any number of ints, a `set[str]` any number of strings, a `dict[str, int]` any number of string-to-int pairs. Tuples are used two very different ways in Python — as a fixed record (`(sku, quantity)`) and as an immutable sequence (`(3, 5, 8, 13)`) — and the annotation syntax has to express both. **The fixed form** lists one type per position: `tuple[str, int]`, `tuple[int, int, bool]`. The arity is part of the type. A checker knows `t[0]` is a `str` and `t[1]` is an `int` when the index is a literal, allows `sku, qty = t`, and rejects a three-element value. **The variadic form** is `tuple[X, ...]`: any number of `X`, zero included. Here `...` is the literal `Ellipsis` object, special-cased by the type system for `tuple`, and it means "more elements of that same type" — never "and then anything else". Because the length is unknown, `a, b = t` does not check, and neither does `t[2]` in general; iteration, `len()`, `in` and slicing are what you get. Two corners round it out: a bare `tuple` with no subscript means `tuple[Any, ...]`, and `tuple[()]` is the type of the empty tuple, occasionally useful as a base case. ### Why picking the wrong one hurts Annotating a fixed pair as `tuple[int, ...]` throws away everything the checker could have done for you. Consider a pick-list builder that slices a **6,800-row** batch into pages and returns the bounds of the current page: ```python def page_bounds(total: int, size: int, page: int) -> tuple[int, int]: start = page * size return start, min(start + size, total) ``` With `tuple[int, int]`, `start, end = page_bounds(6800, 500, 3)` type-checks and a three-name unpack is caught immediately. Annotate the same return as `tuple[int, ...]` and the unpack becomes unverifiable — the checker cannot tell two from three — so a caller that grows the return value later gets no warning at all. The reverse mistake is just as common: annotating `quantities(rows) -> tuple[int, int]` because today's fixture happens to hold two rows. The moment a third row arrives every call site is a type error for a function that was never really fixed-arity. Ask the honest question — *is the length part of the contract?* If yes, the fixed form; if no, the ellipsis form. ### What the fixed form still will not catch This is the senior half of the answer. `tuple[int, int]` says "two ints". It does not say *which* int is which. A page-bounds function that returns `(end, start)` by mistake, or whose second element is an **inclusive** last row while the caller assumes an exclusive stop, type-checks perfectly and produces an off-by-one that only shows up at the edge of the batch — the 6,800th row silently dropped or double-picked. Positional types check shape, not meaning. When the positions carry meaning, name them. `typing.NamedTuple` gives you the names, the annotation and tuple behaviour at once: ```python from typing import NamedTuple class PageBounds(NamedTuple): start: int stop_exclusive: int ``` Now the boundary convention is in the identifier, unpacking still works for callers that want it, and swapping the two fields is a visible mistake at the construction site. A `dataclass` is the same move when tuple behaviour is not wanted. The rule of thumb that survives review: a two-element return of obviously different things is fine as a plain tuple; three or more, or two of the same type where order carries meaning, wants names. ### Reading the forms in context A few spellings you will meet constantly. `list[tuple[str, int]]` is the standard shape of tabular rows — a list of (key, value) pairs, which is exactly what iterating `dict.items()` gives you. `dict[str, tuple[int, ...]]` maps a SKU to an arbitrary run of counts. `*args` in a function is a `tuple`, and annotating `def f(*args: int)` means each argument is an `int`, so the collected `args` is `tuple[int, ...]` — you annotate the element type, not the tuple. ### Runtime versus checking None of this is enforced when the code runs. `tuple[int, str]` evaluates to a `types.GenericAlias`; constructing `(1, 2)` where `tuple[int, str]` was promised raises nothing. The annotation exists for the checker, the reader and the editor. That is why choosing between the two forms is a communication decision, and why the fixed form is worth using whenever the arity really is fixed: it is free documentation that a tool can verify.