Why accept Sequence[Animal] but return list[Animal] from a public function?

### Two positions, two opposite pressures A function signature has an input side and an output side, and variance affects them in mirror-image ways. On the **input** side, the caller supplies the value, so the question is *what can be assigned to my parameter type*. Every widening of the parameter adds callers. Because `collections.abc.Sequence` is declared covariant, `Sequence[Animal]` is satisfied by `list[Animal]`, `list[Dog]`, `tuple[Dog, ...]`, a `range`, a string of characters where appropriate, and any class implementing `__len__` and `__getitem__` as a read-only view. `list[Animal]` is satisfied by exactly one thing: a `list` whose declared element type is precisely `Animal`. That is the invariance of mutable containers, seen from the API author's chair. On the **output** side, your function supplies the value, so the question is *what can my return type be assigned to*. Here narrowness costs nothing and buys a lot. A declared `list[str]` return is automatically usable everywhere a `Sequence[str]` or an `Iterable[str]` is wanted, because the covariance runs in the caller's favour. Declaring the loose type instead throws away capability: a caller who receives a `Sequence[str]` cannot `append` to it, cannot `sort` it in place, and typically writes `list(result)` — an entirely pointless copy of an object your function had already built fresh. ### The guideline in practice Consider a module in an ad-auction bidder that scores a batch of bid records. ```python from collections.abc import Sequence def top_bids(bids: Sequence[Bid], keep: int) -> list[Bid]: return sorted(bids, key=lambda b: b.cents, reverse=True)[:keep] ``` The parameter is a `Sequence` because the body only iterates and indexes. A caller holding a `list[SponsoredBid]`, where `SponsoredBid` subclasses `Bid`, can pass it directly; had the parameter been `list[Bid]` that caller would have been stuck writing a cast or copying the list. The return is `list[Bid]` because `sorted` genuinely built a brand-new list that nobody else holds a reference to, so there is no reason to hide it behind a narrower interface. ### When the loose parameter is wrong The guideline is about *read-only* parameters, and it stops the moment the body writes. - If the function calls `append`, `sort` or item assignment, `Sequence` will not type-check — that is the abstract base class doing its job. Use `collections.abc.MutableSequence[Animal]`, or better, return a new list instead of mutating a caller's container. - If the function iterates the argument **twice**, do not annotate it `Iterable`. An `Iterable` may be a one-shot iterator, and the second pass will silently see nothing. `Sequence` is the honest choice when you need to re-read or need `len`. - If the function stores the argument for later use, think about who else can mutate it. `Sequence` says nothing about immutability, only about the operations *you* promise to use. ### When the tight return is wrong Returning a concrete `list` is the default, not a law. Return a narrower or protective type when you are handing back something you did not just build: - Returning an internal `list` attribute directly hands callers a live handle on your object's state. Returning a copy, or a read-only view declared as `Sequence`, is the safer contract — and there the loose annotation carries real information rather than losing it. - If you may later change the concrete type from a `list` to something else, a declared `Sequence` return keeps that freedom. Decide once, deliberately, and write it down; do not oscillate. ### The related mistakes Two failure modes show up repeatedly in review. The first is annotating a parameter `list[Animal]` out of habit and then, when a caller with a `list[Dog]` complains, reaching for `typing.Any` or a cast. That trades a compile-time conversation for a silent runtime hazard. The second is annotating everything — parameters *and* returns — as `Iterable`, which produces an API where every consumer starts by materialising the result and where re-iteration bugs are one refactor away. ### Version notes Use the abstract base classes from `collections.abc`, subscripted directly: `Sequence[Bid]`, `Iterable[Bid]`, `Mapping[str, Bid]`. This has worked in annotations since Python 3.9 (PEP 585), and the `typing.Sequence` and `typing.Iterable` aliases are deprecated in favour of it. The variance of these classes is unchanged on 3.14. ### A checklist for one signature Working through a single function, four questions settle every annotation on it. Does the body mutate the argument? If yes, the loose read-only type is unavailable and you should probably return a new container instead. Does the body traverse the argument more than once, or need `len`? If yes, `Sequence`, not `Iterable`. Did the function build the returned object itself? If yes, return the concrete type. Is the returned object internal state? If yes, return a copy, or declare the read-only type and mean it. None of these questions is about variance directly, but each one is decided by it.