Type Hints em Python: guia completo de anotações de tipos

O que são Type Hints em Python

Type Hints (anotações de tipos) — são um sistema para indicar os tipos de dados esperados no código Python, que melhora a legibilidade, confiabilidade e qualidade do software. Embora Python continue sendo uma linguagem de tipagem dinâmica, a possibilidade de especificar tipos explicitamente ajuda a evitar diversos erros durante o desenvolvimento.

Por que usar anotações de tipos

Python é conhecido por sua flexibilidade, mas isso muitas vezes leva a bugs ocultos devido a tipos de dados inesperados. Veja um exemplo sem anotações:

def add(a, b):
    return a + b

print(add(5, 10))    # 15
print(add("5", "10"))  # '510' — resultado inesperado

A expressão add("5", "10") não gera erro, mas o resultado pode surpreender o desenvolvedor.

Type Hints resolvem os seguintes problemas:

• Indicação explícita de tipos de argumentos e valores de retorno
• Melhora da legibilidade do código para a equipe de desenvolvimento
• Análise estática para encontrar erros antes da execução do programa
• Autocompletar na IDE com sugestões mais precisas
• Documentação de API sem comentários adicionais

Exemplos básicos de uso de Type Hints

Anotação de funções

def add(a: int, b: int) -> int:
    return a + b

def calculate_area(radius: float) -> float:
    return 3.14159 * radius ** 2

def format_greeting(name: str) -> str:
    return f"Olá, {name}!"

Anotação de variáveis

name: str = "Alice"
age: int = 30
pi: float = 3.14159
is_active: bool = True

Trabalhando com coleções

from typing import List, Dict, Tuple, Set

def process_scores(scores: List[int]) -> float:
    return sum(scores) / len(scores)

def get_user_data() -> Dict[str, str]:
    return {"name": "João", "email": "joao@exemplo.com"}

def get_coordinates() -> Tuple[float, float]:
    return (10.5, 20.3)

def unique_values(items: List[str]) -> Set[str]:
    return set(items)

Recursos avançados de Type Hints

Optional e Union

from typing import Optional, Union

def greet(name: Optional[str] = None) -> str:
    if name:
        return f"Olá, {name}!"
    return "Olá, Convidado!"

def process_value(value: Union[int, float, str]) -> str:
    return str(value)

# No Python 3.10+ você pode usar o operador |
def process_new_syntax(value: int | float | str) -> str:
    return str(value)

Tipos Callable

from typing import Callable

def apply_function(func: Callable[[int, int], int], a: int, b: int) -> int:
    return func(a, b)

def multiply(x: int, y: int) -> int:
    return x * y

result = apply_function(multiply, 5, 3)  # 15

Tipos Genéricos (Generic)

from typing import TypeVar, Generic, List

T = TypeVar('T')

class Stack(Generic[T]):
    def __init__(self) -> None:
        self.items: List[T] = []
    
    def push(self, item: T) -> None:
        self.items.append(item)
    
    def pop(self) -> T:
        if not self.items:
            raise IndexError("Pilha vazia")
        return self.items.pop()
    
    def is_empty(self) -> bool:
        return len(self.items) == 0

# Uso
int_stack = Stack[int]()
int_stack.push(42)

Anotações em classes

from typing import List, Optional
from dataclasses import dataclass

class Person:
    def __init__(self, name: str, age: int, email: Optional[str] = None) -> None:
        self.name = name
        self.age = age
        self.email = email
    
    def get_info(self) -> str:
        return f"{self.name}, {self.age} anos"

@dataclass
class Product:
    name: str
    price: float
    quantity: int = 0
    
    def total_value(self) -> float:
        return self.price * self.quantity

Ferramentas para análise estática

Para aproveitar ao máximo os Type Hints, use estas ferramentas:

• Mypy — o verificador de tipos mais popular para Python
• Pyright — ferramenta rápida da Microsoft, usada no VS Code
• Pyre — verificador de tipos do Facebook (Meta)
• Pytype — ferramenta do Google que também infere tipos

Exemplo de uso com mypy:

pip install mypy
mypy meu_arquivo.py

Melhores práticas

• Seja consistente: use Type Hints em todo o projeto ou em nenhum lugar
• Prefira tipos específicos: use List[int] em vez de list
• Use Any com moderação: evite Any a menos que seja realmente necessário
• Aproveite recursos do Python 3.10+: operador | para Union e TypeAlias
• Documente exceções: tipos não cobrem exceções, então documente-as separadamente

Conclusão

Type Hints em Python são uma ferramenta poderosa para escrever código mais seguro, legível e de fácil manutenção. Combinados com ferramentas de análise estática como mypy, eles ajudam a detectar erros cedo e melhoram a produtividade da equipe. Comece a usar Type Hints hoje mesmo e eleve a qualidade do seu código Python!