mypy na prática e quando tipar

Instalar e rodar o mypy

O mypy é uma ferramenta separada do Python, instalada com pip, do mesmo jeito que você instalou pacotes no Intermediário. Depois de instalado, você o roda pela linha de comando apontando para um arquivo ou uma pasta. Ele lê o código, sem executar nada, e imprime as incoerências de tipo que encontrar. Quando não acha problema, ele diz que não há erros. É essa checagem, feita antes de rodar, que transforma os type hints de mera documentação em verificação de verdade.

# Arquivo: contas.py
def dobro(valor: int) -> int:
    return valor * 2

resultado = dobro("dez")  # erro: passou str onde se espera int
print(resultado)

# No terminal:
#   pip install mypy
#   mypy contas.py
# Saida aproximada:
#   contas.py:4: error: Argument 1 to "dobro" has incompatible type "str"; expected "int"

O mypy aponta a linha e a incoerência: str passado onde se esperava int.

Repare que o Python rodaria esse arquivo e só quebraria mais adiante, com uma mensagem confusa, ou pior, produziria um resultado errado em silêncio. O mypy pega o problema na origem, apontando a linha exata e explicando que a função dobro esperava um int e recebeu um str. Essa é a diferença entre um erro caçado antes de rodar e um bug descoberto em produção.

Os erros mais comuns do mypy

A maioria dos erros do mypy cai em poucos padrões. O mais comum é o tipo incompatível, quando você passa algo do tipo errado para uma função. Logo depois vem o has no attribute, quando você chama um método que aquele tipo não possui, sinal de que o objeto não é o que você pensava. Muito frequente também é esquecer de tratar o None: se o tipo é X | None e você usa o valor direto, o mypy cobra a checagem. Ler a mensagem com calma quase sempre aponta o conserto.

def primeiro_nome(nome_completo: str | None) -> str:
    # Sem tratar None, o mypy reclama: str | None nao tem .split garantido
    if nome_completo is None:
        return "Anonimo"
    return nome_completo.split()[0]

print(primeiro_nome("Ana Silva"))  # Ana
print(primeiro_nome(None))         # Anonimo

Tratar o None com um if antes de usar o valor silencia o erro e evita o bug.

Quando vale a pena tipar

A decisão mais importante do módulo não é de sintaxe, é de julgamento. Tipar tem um custo: leva tempo escrever e manter as anotações. Onde esse custo compensa? Em código que outras pessoas vão usar, como bibliotecas e módulos compartilhados, os tipos são documentação viva e evitam mau uso. Em lógica complexa e cálculos importantes, eles pegam erros cedo. Nas fronteiras entre partes do sistema, deixam os contratos explícitos. Já num script de dez linhas que você roda uma vez e joga fora, tipar é esforço sem retorno.

A tipagem gradual do Python existe justamente para essa flexibilidade: você adiciona tipos onde eles pagam e deixa de fora onde não pagam. O bom senso é o guia. Comece anotando as assinaturas das funções públicas e as estruturas de dados centrais; deixe o resto para depois, se precisar. Com o mypy conferindo essas partes, você ganha o essencial da segurança de tipos sem transformar cada linha num exercício de anotação. É assim que a tipagem estática vira aliada, e não fardo.