Type hints: o contrato explícito

A sintaxe dos type hints

Um type hint é uma anotação que diz qual tipo você espera. A sintaxe é direta: depois do nome do parâmetro você escreve dois pontos e o tipo, e depois da lista de parâmetros você usa uma seta para anotar o retorno. Nada além disso muda na função. Ela continua rodando igual, porque o Python lê essas anotações e as guarda, mas não obriga o valor a seguir o tipo. É por isso que os type hints são chamados de gradual typing: você adiciona onde quer, na medida em que quer.

def area_retangulo(base: float, altura: float) -> float:
    return base * altura

def saudar(nome: str, formal: bool = False) -> str:
    if formal:
        return f"Prezado(a) {nome}"
    return f"Oi, {nome}"

print(area_retangulo(3.0, 4.0))  # 12.0
print(saudar("Ana"))            # Oi, Ana
print(saudar("Dr. Silva", True))  # Prezado(a) Dr. Silva

Parâmetros anotados com : tipo e retorno com -> tipo. O default convive com o hint.

Repare que um parâmetro com valor padrão convive com a anotação: escreve-se formal: bool = False, ou seja, o tipo vem antes do sinal de igual. A ordem é sempre nome, depois tipo, depois valor padrão. Essa é a base de tudo que vem a seguir no módulo; os tipos mais elaborados, como listas de inteiros ou valores opcionais, apenas trocam a parte do tipo por algo mais expressivo.

Tipos básicos e anotação de variáveis

Os tipos mais simples são os próprios tipos embutidos: int para inteiros, float para decimais, str para texto, bool para verdadeiro ou falso. Você também pode anotar uma variável, não só um parâmetro, escrevendo o nome, dois pontos e o tipo. Isso é útil quando o valor inicial não deixa o tipo óbvio, ou quando você quer declarar uma variável antes de atribuir. O mypy usa essas anotações para conferir o resto do código.

total: int = 0
nome: str = "Ana"
preco: float = 19.9
ativo: bool = True

# Anotar sem atribuir de imediato tambem vale:
resultado: float
resultado = total * preco
print(resultado)  # 0.0

Variáveis anotadas com : tipo. A anotação pode vir antes da atribuição.

O que o Python faz com as anotações

Vale insistir neste ponto porque ele confunde muita gente. Em tempo de execução, o Python não verifica os type hints. Se você anotar idade: int e passar o texto trinta, o programa roda até algo dar errado por outro motivo. As anotações ficam guardadas no atributo __annotations__ da função e servem para três públicos: você, que lê o contrato; o editor, que autocompleta e avisa; e o mypy, que confere sem rodar. Nenhum deles muda o comportamento em execução.

Essa separação é saudável. O type hint cuida da coerência do seu código: garantir que uma função que espera número não receba texto por engano de outra parte do programa. A validação de dados de fora, como o que vem de um formulário, continua sendo trabalho seu, com ifs e mensagens claras. Um não substitui o outro. Com essa base firme, a próxima aula abre o módulo typing, que dá nomes a tipos mais ricos, como listas de inteiros e valores opcionais.