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:
Iterableaceita listas, geradores e iteradores personalizadosIteratoré de passagem única - o verificador avisa se for reutilizado incorretamente no modo estritoMappingdocumenta dicionários somente leitura sem métodos de mutaçãoCallable[[], 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
isinstanceem tempo de execução e alvos de tipagem estrutural. - typing vs collections.abc - Prefira
collections.abcem anotações (3.9+). - Genéricos aninhados -
dict[str, list[int]]para listas de adjacência.
Escolhas Comuns de ABC
| Aceita | Quando |
|---|---|
Sequence | Necessita de indexação + len |
Iterable | Passagem única para frente |
Mapping | Pesquisa de chave somente leitura |
MutableMapping | Necessita de setitem/delitem |
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.Listdepreciado 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 comdict[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 fixotuple[int, str].
Alternativas
| Alternativa | Use Quando | Não Use Quando |
|---|---|---|
TypedDict | Chaves de string conhecidas | Apenas chaves dinâmicas |
| Modelo Pydantic | JSON aninhado validado | Núcleo numérico interno |
TypeAlias | Alias aninhado complexo | Simples list[int] |
numpy.ndarray | Tensores numéricos | Contêineres Python gerais |
FAQs
Sequence vs list?
Tipo de parâmetro Sequence quando você apenas lê/indexa; list quando o chamador deve passar especificamente uma lista mutável.
Iterable vs Iterator?
Iterable produz um iterador via iter(). Iterator é esgotado após uma passagem.
Mapping vs dict?
Mapping sinaliza API somente leitura; dict quando a função muta ou retorna um dict concreto.
genéricos de set?
set[str] para conjuntos homogêneos - invariante como list.
tipagem de frozenset?
frozenset[str] igual a set para fins de tipagem.
tipo de retorno de gerador?
Iterator[T] ou Iterable[T] - Iterator tem semântica de passagem única mais estrita.
bytes e memoryview?
bytes para binário; memoryview raramente em APIs públicas - use tipos do protocolo Buffer em tipagem avançada.
dict JSON aninhado?
dict[str, object] é flexível; TypedDict ou modelos para segurança real.
callable vs Callable?
collections.abc.Callable é preferível em anotações 3.9+.
list somente leitura?
Sequence[T] - sem append no contrato de tipo, embora a lista em tempo de execução ainda seja mutável.
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+.