Built-in & Collection Generics

Modern Python uses built-in collection generics (list[int]) and collections.abc abstract types to describe containers precisely - both for readers and for mypy/pyright.

Recipe

from collections.abc import Iterable, Mapping, Sequence
 
def total_lengths(names: Sequence[str]) -> int:
    return sum(len(n) for n in names)
 
def merge(base: Mapping[str, int], extra: Mapping[str, int]) -> dict[str, int]:
    return {**base, **extra}

When to reach for this:

• Public function parameters accepting any sequence
• Read-only dict APIs without mutation
• Typing JSON-like nested structures
• Iterator-consuming utilities

Working Example

from collections.abc import Callable, Iterable, Iterator, Mapping
 
def index_by(items: Iterable[dict], key: str) -> dict[str, dict]:
    result: dict[str, dict] = {}
    for item in items:
        result[str(item[key])] = item
    return result
 
def batch(iterator: Iterator[int], size: int) -> Iterable[list[int]]:
    batch_items: list[int] = []
    for value in iterator:
        batch_items.append(value)
        if len(batch_items) == size:
            yield batch_items
            batch_items = []
    if batch_items:
        yield batch_items
 
def apply_all(fns: Mapping[str, Callable[[], None]]) -> None:
    for fn in fns.values():
        fn()
 
if __name__ == "__main__":
    rows = [{"id": "1", "name": "Ada"}, {"id": "2", "name": "Linus"}]
    print(index_by(rows, "id"))

What this demonstrates:

• Iterable accepts list, generator, and custom iterators
• Iterator is single-pass - checker warns if reused incorrectly in strict mode
• Mapping documents read-only dict-like without mutation methods
• Callable[[], None] types zero-arg side-effect functions

Deep Dive

How It Works

• PEP 585 - Built-in generics in 3.9+ (list[int]).
• Variance - Most container generics invariant (list[Dog] not list[Animal]).
• collections.abc - Runtime isinstance checks and structural typing targets.
• typing vs collections.abc - Prefer collections.abc in annotations (3.9+).
• Nested generics - dict[str, list[int]] for adjacency lists.

Common ABC Choices

Python Notes

# invariant list - use Sequence for read-only param
def print_all(items: Sequence[str]) -> None:
    for item in items:
        print(item)

Gotchas

• list vs List - typing.List deprecated style on 3.9+. Fix: list[int].
• Iterable consumed twice - Type hint does not stop double iteration bug. Fix: Document or require Sequence.
• dict keys invariant - dict[str, int] not compatible with dict[str, float] in strict variance. Fix: Use values union or Mapping.
• Any in inner type - dict[str, Any] loses safety. Fix: TypedDict or Pydantic model.
• tuple variable length - tuple[int, ...] for homogeneous variable length vs fixed tuple[int, str].

Alternatives

FAQs

Related

• Type Hints Basics - intro
• TypedDict & NamedTuple - structured dicts
• Optional, Union & the | Operator - unions in containers
• Generics & TypeVar - parametric types

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.