Escolher contratos de coleções e iteradores

Uma chamada pode passar uma list ou um dict, mas isso não torna esses tipos requisitos da função. Antes de anotar um parâmetro, observe quais operações o corpo realmente executa.

Se uma função só lê valores, uma anotação concreta pode restringir chamadas válidas sem trazer benefício. Em vez de perguntar “qual objeto apareceu no exemplo?”, pergunte: “de que operações esta implementação precisa?”

A representação concreta usada por quem chama e o contrato exigido pela função são decisões diferentes.

O módulo collections.abc disponibiliza contratos prontos para anotações. Eles descrevem operações oferecidas por um objeto; você não precisa criar classes próprias para usá-los.

Nas próximas etapas, você vai escolher contratos específicos conforme a necessidade de percorrer, avançar, acessar posições ou consultar chaves. Por enquanto, retenha o critério: selecione a interface menos restritiva que ainda cubra todas as operações usadas.

A função só percorre os nomes; ela não usa nenhuma operação exclusiva de list.

A entrada deve aceitar tudo o que a implementação consegue usar corretamente. Já o retorno deve expressar o que sua API quer oferecer a quem chama.

Assim, uma função pode aceitar uma interface ampla e ainda devolver uma list[str] se pretende entregar um resultado materializado, reutilizável e próprio para operações de lista. Generalizar toda saída automaticamente pode enfraquecer uma promessa útil da API.

Use Iterable[T] quando a função precisa apenas obter valores de tipo T em uma iteração, por exemplo, com for.

Em vez de exigir list[T], a assinatura passa a aceitar diversas fontes compatíveis: listas, tuplas homogêneas, conjuntos e geradores. A escolha é válida quando a implementação não depende de posição, tamanho ou avanço explícito.

Todas estas fontes podem alimentar uma função que faz uma única passagem com for.

A implementação já faz somente uma passagem. Portanto, apenas o contrato do parâmetro precisa mudar.

Se uma função genérica devolve um elemento que recebeu, mantenha o mesmo parâmetro de tipo. Troque apenas o contêiner concreto pelo contrato necessário.

T continua ligando o tipo produzido ao tipo dos elementos fornecidos.

Iterator[T] é um contrato para uma fonte que pode ser percorrida e avançada com next(). Use-o no parâmetro quando a função precisa consumir o estado do objeto recebido.

Se a função só precisa percorrer valores, Iterable[T] continua sendo o contrato menos restritivo. Ela pode obter um iterador local com iter(fonte) sem alterar o contrato de entrada.

Compare o que cada contrato disponibiliza diretamente para a implementação.

O retorno preserva o tipo do próximo valor.

Uma função que contém yield não devolve imediatamente cada valor produzido. Ao ser chamada, ela cria e retorna um objeto iterador.

Na anotação Iterator[str], str é o tipo de cada valor produzido por yield — não o tipo do objeto devolvido pela chamada.

Cada execução de yield produz uma str; por isso, o retorno é Iterator[str].

Use Sequence[T], de collections.abc, quando a implementação precisa de uma coleção ordenada por posições. Esse contrato disponibiliza iteração, len(...) e acesso por índice, como itens[0].

Assim, uma função que consulta o primeiro e o último elemento não precisa exigir list[T]: ela precisa de uma sequência.

Compare os contratos pelo que a função realmente faz.

A função usa len e índices; por isso, Sequence[T] é o contrato mínimo adequado.

O mesmo parâmetro T aparece na entrada e no retorno: para Sequence[int], o resultado é tuple[int, int]; para Sequence[str], é tuple[str, str].

Listas e tuplas homogêneas compatíveis podem ser passadas. Já um gerador fornece valores por iteração, mas não oferece len nem itens[0] pelo contrato Iterable[T].

Use Mapping[K, V] quando a função precisa consultar pares de chave e valor, mas não precisa alterar o mapeamento. Esse contrato preserva os tipos: K representa as chaves e V, os valores.

Ele permite acesso por chave (dados[chave]), teste de pertencimento (chave in dados) e iteração por pares com dados.items(). Um dict pode ser passado para um parâmetro Mapping, mas a função não fica limitada a exigir um dicionário concreto.

A chave recebida tem o mesmo tipo K das chaves do mapeamento, e o resultado tem tipo V.

Não anote como Mapping uma função que atribui, remove ou atualiza entradas. Essas operações não fazem parte do contrato de consulta.

Se a implementação abaixo deve modificar um dicionário, mantenha um contrato que permita essa escrita, como dict[str, int]. Não substitua por Mapping só para torná-la mais genérica.

Iterable[T] permite obter elementos por iteração, mas não promete que a fonte tenha tamanho conhecido, seja finita, possa recomeçar ou entregue os mesmos elementos em uma segunda passagem. Uma lista costuma permitir essas expectativas; um gerador, não.

Do mesmo modo, Sequence[T] não garante que exista algum elemento, e Mapping[K, V] não garante que uma chave específica esteja presente. Essas são precondições do problema, não consequências da anotação.

Esta função usa duas passagens: uma para somar e outra para contar. Ambas são operações permitidas sobre Iterable[int], portanto a anotação é válida. Mas um iterador pode já estar esgotado quando a segunda passagem começa.

Se total e quantidade bastam, calcule os dois no mesmo laço. Assim, a função continua aceitando listas, tuplas, conjuntos e geradores sem pressupor reinício.

Materializar com itens = list(valores) também permite múltiplas passagens, mas é uma decisão explícita: só faz sentido quando a fonte é finita e manter todos os elementos em memória é aceitável. Iterable não oferece essas garantias.

Ao receber Sequence[T] ou Mapping[K, V], sua função declara as operações de consulta de que precisa. No código tipado, isso impede chamar métodos de alteração que não pertencem a esses contratos, como append em uma Sequence ou atribuição por chave em um Mapping.

Mas a anotação não transforma o argumento em uma cópia nem altera seu tipo concreto. Se quem chamou a função passou uma list ou um dict, esse objeto continua mutável por outras referências.

A função consulta pelo contrato; outra referência ainda pode alterar a mesma lista ou o mesmo dicionário.

Crie um arquivo e execute este código.

Em um arquivo analisado pelo mypy, estas linhas são incompatíveis com os contratos dos parâmetros.

Esses erros não afirmam que uma lista nunca pode receber append ou que um dicionário nunca pode mudar. Eles afirmam que, por essa referência anotada como interface de consulta, a função não pode depender dessas operações.

Se a API precisa alterar a coleção, o contrato deve expressar essa necessidade. Se apenas consulta, Sequence ou Mapping deixa essa intenção explícita — sem prometer que o conteúdo ficará estável.

Leia a implementação antes de anotar a assinatura. A fonte de chaves será apenas percorrida: use Iterable[K]. O catálogo será consultado por chave: use Mapping[K, V]. A transformação produz valores sob demanda e permite next(): retorne Iterator[V]. Já a seleção usa len implícito no acesso e posição por índice: ela precisa de Sequence[T].

Não generalize o retorno por reflexo: escolha o que sua API pretende oferecer a quem chama.

Compare as operações de cada função com o contrato mínimo que as disponibiliza.

No seu computador, crie um arquivo chamado contratos.py com o código completo abaixo. Ele inclui chamadas com lista, tupla e gerador; nenhuma delas deve exigir conversão prévia para list ou dict.

No terminal, no diretório do arquivo, execute os dois comandos. O primeiro confirma o comportamento dos casos incluídos; o segundo verifica se as operações usadas respeitam as anotações.