Preservar relações de tipos em funções genéricas

Considere uma função cujo comportamento é simplesmente devolver o valor que recebeu. Ela aceita vários tipos, mas o ponto importante não é apenas quais tipos entram: é que o tipo que sai deve acompanhar o tipo que entrou em cada chamada.

Uma assinatura ampla pode aceitar corretamente str e int, mas ainda apagar essa ligação para quem chama a função.

Cada chamada tem uma correspondência própria entre entrada e retorno.

As três funções devolvem o argumento recebido, mas suas anotações informam coisas diferentes ao verificador.

object aceita valores de qualquer tipo, mas o retorno fica conhecido apenas como object. Any vai além: desliga a verificação nas operações posteriores.

A união parece mais específica, porém str | int no retorno só diz que uma das alternativas será devolvida. Ela não registra a regra: “se entrou str, sai str; se entrou int, sai int”. Assim, mesmo ao passar 42, o resultado continua sendo tratado como str | int.

Para uma função de identidade, o contrato desejado não é “aceita texto ou número”. É “para qualquer tipo escolhido nesta chamada, devolve esse mesmo tipo”.

Um parâmetro de tipo representa essa variável de relação: ele será determinado conforme o tipo estático disponível em cada uso da função. Na próxima etapa, você vai declarar essa relação na sintaxe do Python 3.12.

Quando uma função recebe um valor e o devolve sem transformá-lo, declare um parâmetro de tipo entre colchetes após o nome da função. Em def identidade[T](valor: T) -> T:, o mesmo T liga o argumento ao retorno.

Esse T existe no escopo da função identidade: ele não é um tipo concreto fixado uma única vez no arquivo.

Você chama a função normalmente. Não escreva identidade[str](...): o verificador infere T a partir do argumento disponível naquela chamada.

A inferência preserva o tipo estático que o código já conhece. Ela não inspeciona o objeto em execução para descobrir uma classe mais específica do que a anotação da variável.

Execute este arquivo com Python 3.12 e verifique-o com python -m mypy nome_do_arquivo.py.

No seu editor, crie um arquivo com a função abaixo. Acrescente duas chamadas: uma com uma lista de inteiros e outra com uma tupla de textos. Depois, ponha reveal_type em cada resultado e execute o mypy. A função deve continuar usando apenas T.

Uma função que escolhe um item de uma lista recebe uma coleção, mas devolve um elemento dela. Por isso, a relação correta é list[T] → T: o mesmo T representa o tipo dos elementos na entrada e o tipo do resultado.

Não use list[T] → list[T] quando a função retorna apenas um item. Isso prometeria uma coleção como resultado.

Python 3.12 ou superior

Em cada chamada, o verificador infere T a partir do tipo conhecido da lista. Com list[str], o retorno é str. Se os elementos já são int | str, o retorno continua sendo int | str; a função não escolhe uma alternativa mais específica por observar o objeto em execução.

Repetir T pede compatibilidade com o tipo inferido. Se houver mais de uma fonte de inferência na chamada, o verificador pode chegar a um tipo mais amplo que satisfaça todas elas.

Em uma função declarada com def identidade[T](valor: T) -> T, T não significa “o tipo dos exemplos que testei”. Ele pode representar qualquer tipo inferido em uma chamada. Por isso, o corpo precisa ser válido para todos esses tipos possíveis.

É seguro receber, armazenar, encaminhar e devolver um valor de T. Já chamar um método exclusivo de str ou somar um número pressupõe um contrato que a assinatura ainda não forneceu.

Compare operações que apenas transportam o valor com operações que dependem de uma característica específica dele.

Uma operação pode ser válida na coleção e inválida em cada elemento. Por exemplo, valores.append(novo) é uma operação da lista; isso não autoriza usar .append() em um valor individual de tipo T.

Exemplos para salvar em um arquivo Python 3.12 e verificar com mypy.

Em uma seleção, o elemento de entrada e o resultado podiam compartilhar o mesmo parâmetro de tipo. Já uma transformação pode mudar o tipo: por exemplo, converter uma lista de int em uma lista de str.

Use dois parâmetros independentes: T é o tipo de cada elemento fornecido pela lista, e R é o tipo retornado pelo callback. A assinatura conecta os três pontos: list[T], Callable[[T], R] e list[R].

Crie um arquivo transformar.py com este código e execute python -m mypy transformar.py no seu ambiente.

Na chamada mapear(numeros, rotulo), a lista informa T = int. A assinatura de rotulo informa que ela recebe int e devolve str, portanto R = str. Logo, rotulos é inferida como list[str].

Não especialize a função na chamada com colchetes: a inferência usa a coleção e o callback. Remova reveal_type antes de executar o arquivo normalmente.

Um parâmetro de tipo irrestrito poderia representar qualquer tipo, então seu corpo não pode pressupor métodos específicos. Quando a função precisa usar uma operação garantida por uma classe base, declare um limite superior:

def normalizar[T: Documento](item: T) -> T:

Aqui, T pode ser Documento ou qualquer subtipo compatível. Dentro da função, o verificador sabe que todo T possui as operações declaradas em Documento.

O limite permite acessar o contrato comum, mas T mantém a identidade estática do subtipo recebido.

Exemplo em Python 3.12: a operação usada está no contrato da classe base, e o objeto devolvido continua sendo T.

A anotação é analisada pelo verificador de tipos. Ela não adiciona uma checagem automática quando o programa roda, nem impede que dados externos incorretos cheguem ao código. Validações necessárias em tempo de execução continuam sendo responsabilidade explícita do programa.

Um parâmetro de tipo é útil quando conecta posições da assinatura. Ele pode dizer, por exemplo: “o retorno tem o mesmo tipo da entrada” (T → T) ou “o callback transforma T em R”.

Se essa relação não existe, um genérico pode só tornar a assinatura mais abstrata, sem informar nada novo ao chamador.

As três assinaturas podem aceitar valores variados, mas prometem coisas diferentes sobre o resultado.

Compare estas versões:

def registrar[T](valor: T) -> None:
    print(valor)

def registrar(valor: object) -> None:
    print(valor)

Como o retorno é None e não há outra posição ligada a T, o primeiro contrato não preserva uma relação útil. A segunda versão comunica diretamente que a função só recebe um valor para exibi-lo.

Da mesma forma, use uma união quando ela descreve alternativas reais sem correlação: def codigo(valor: int | str) -> str sempre produz str, seja qual for a alternativa recebida.

Nesta aplicação, cada função responde a uma pergunta diferente:

• selecionar: de list[T], obter um T;
• transformar: de list[T] e Callable[[T], R], obter list[R];
• preservar subtipo: aceitar um T limitado por uma classe base, usar uma operação da base e devolver o mesmo T.

Ao compor as chamadas, acompanhe o tipo estático em cada etapa. O objetivo não é aceitar “qualquer coisa”, e sim manter a informação que já existe no ponto de chamada.

O diagrama mostra como cada assinatura transporta a informação de tipo até o resultado.

Crie um arquivo chamado relacoes.py e copie o código abaixo. As implementações já estão completas; substitua apenas as três assinaturas amplas pelas assinaturas genéricas adequadas.

Use parâmetros de tipo declarados diretamente nas funções, na sintaxe do Python 3.12. Não introduza Any, casts nem supressões de diagnóstico.

Compare somente depois de tentar. Execute python -m mypy --strict relacoes.py e leia os três resultados de reveal_type.

Se o verificador apontar um erro, revise primeiro a relação prometida e todos os caminhos de retorno. Evite “resolver” o diagnóstico com Any ou uma supressão: isso interrompe justamente a evidência estática que você quer acompanhar.

Depois da verificação, remova os reveal_type, pois eles servem apenas à inspeção do mypy.