Tipos Genéricos Integrados e de Coleção

O Python moderno usa genéricos de coleção integrados (list[int]) e tipos abstratos de collections.abc para descrever contêineres com precisão - tanto para leitores quanto para mypy/pyright.

Receita

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}

Quando usar isso:

• Parâmetros de função pública que aceitam qualquer sequência
• APIs de dicionário somente leitura sem mutação
• Tipagem de estruturas aninhadas semelhantes a JSON
• Utilitários que consomem iteradores

Exemplo de Trabalho

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"))

O que isso demonstra:

• Iterable aceita listas, geradores e iteradores personalizados
• Iterator é de passagem única - o verificador avisa se for reutilizado incorretamente no modo estrito
• Mapping documenta dicionários somente leitura sem métodos de mutação
• Callable[[], None] tipa funções de efeito colateral sem argumentos

Mergulho Profundo

Como Funciona

• PEP 585 - Genéricos integrados no 3.9+ (list[int]).
• Variância - A maioria dos genéricos de contêineres são invariantes (list[Dog] não é list[Animal]).
• collections.abc - Verificações isinstance em tempo de execução e alvos de tipagem estrutural.
• typing vs collections.abc - Prefira collections.abc em anotações (3.9+).
• Genéricos aninhados - dict[str, list[int]] para listas de adjacência.

Escolhas Comuns de ABC

Notas do Python

# lista invariante - use Sequence para parâmetro somente leitura
def print_all(items: Sequence[str]) -> None:
    for item in items:
        print(item)

Armadilhas

• list vs List - Estilo typing.List depreciado no 3.9+. Correção: list[int].
• Iterable consumido duas vezes - A dica de tipo não impede o bug de iteração dupla. Correção: Documentar ou exigir Sequence.
• chaves de dict invariantes - dict[str, int] não é compatível com dict[str, float] em variância estrita. Correção: Use união de valores ou Mapping.
• Any no tipo interno - dict[str, Any] perde a segurança. Correção: TypedDict ou modelo Pydantic.
• tupla de comprimento variável - tuple[int, ...] para comprimento variável homogêneo vs fixo tuple[int, str].

Alternativas

FAQs

Relacionados

• Noções Básicas de Dicas de Tipo - introdução
• TypedDict & NamedTuple - dicts estruturados
• Optional, Union & o Operador | - uniões em contêineres
• Genéricos & TypeVar - tipos paramétricos

Versões da Pilha: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 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+ e uv 0.6+.