Segurança de Tipos em Python

Utilize o sistema de tipos do Python para capturar erros em tempo de análise estática. Anotações de tipo servem como documentação forçada que as ferramentas validam automaticamente.

Quando Usar Esta Habilidade

• Adicionar dicas de tipo a código existente
• Criar classes genéricas e reutilizáveis
• Definir interfaces estruturais com protocolos
• Configurar mypy ou pyright para verificação rigorosa
• Entender o estreitamento de tipos e guardas
• Construir APIs e bibliotecas seguras quanto a tipos

Conceitos Principais

1. Anotações de Tipo

Declare os tipos esperados para parâmetros de função, valores de retorno e variáveis.

2. Genéricos

Escreva código reutilizável que preserva informações de tipo entre diferentes tipos.

3. Protocolos

Defina interfaces estruturais sem herança (duck typing com segurança de tipo).

4. Estreitamento de Tipos

Use guardas e condicionais para estreitar tipos dentro de blocos de código.

Início Rápido

def get_user(user_id: str) -> User | None:
    """Return type makes 'might not exist' explicit."""
    ...

# Type checker enforces handling None case
user = get_user("123")
if user is None:
    raise UserNotFoundError("123")
print(user.name)  # Type checker knows user is User here

Padrões Fundamentais

Padrão 1: Anotar Todas as Assinaturas Públicas

Toda função, método e classe pública deve ter anotações de tipo.

def get_user(user_id: str) -> User:
    """Retrieve user by ID."""
    ...

def process_batch(
    items: list[Item],
    max_workers: int = 4,
) -> BatchResult[ProcessedItem]:
    """Process items concurrently."""
    ...

class UserRepository:
    def __init__(self, db: Database) -> None:
        self._db = db

    async def find_by_id(self, user_id: str) -> User | None:
        """Return User if found, None otherwise."""
        ...

    async def find_by_email(self, email: str) -> User | None:
        ...

    async def save(self, user: User) -> User:
        """Save and return user with generated ID."""
        ...

Use mypy --strict ou pyright em CI para capturar erros de tipo precocemente. Para projetos existentes, ative o modo rigoroso incrementalmente usando substituições por módulo.

Padrão 2: Usar Sintaxe Moderna de União

Python 3.10+ fornece uma sintaxe de união mais limpa.

# Preferred (3.10+)
def find_user(user_id: str) -> User | None:
    ...

def parse_value(v: str) -> int | float | str:
    ...

# Older style (still valid, needed for 3.9)
from typing import Optional, Union

def find_user(user_id: str) -> Optional[User]:
    ...

Padrão 3: Estreitamento de Tipos com Guardas

Use condicionais para estreitar tipos para o verificador de tipos.

def process_user(user_id: str) -> UserData:
    user = find_user(user_id)

    if user is None:
        raise UserNotFoundError(f"User {user_id} not found")

    # Type checker knows user is User here, not User | None
    return UserData(
        name=user.name,
        email=user.email,
    )

def process_items(items: list[Item | None]) -> list[ProcessedItem]:
    # Filter and narrow types
    valid_items = [item for item in items if item is not None]
    # valid_items is now list[Item]
    return [process(item) for item in valid_items]

Padrão 4: Classes Genéricas

Crie contêineres reutilizáveis seguros quanto a tipos.

from typing import TypeVar, Generic

T = TypeVar("T")
E = TypeVar("E", bound=Exception)

class Result(Generic[T, E]):
    """Representa um valor de sucesso ou um erro."""

    def __init__(
        self,
        value: T | None = None,
        error: E | None = None,
    ) -> None:
        if (value is None) == (error is None):
            raise ValueError("Exatamente um de value ou error deve ser definido")
        self._value = value
        self._error = error

    @property
    def is_success(self) -> bool:
        return self._error is None

    @property
    def is_failure(self) -> bool:
        return self._error is not None

    def unwrap(self) -> T:
        """Obtém o valor ou levanta o erro."""
        if self._error is not None:
            raise self._error
        return self._value  # type: ignore[return-value]

    def unwrap_or(self, default: T) -> T:
        """Obtém o valor ou retorna o padrão."""
        if self._error is not None:
            return default
        return self._value  # type: ignore[return-value]

# O uso preserva os tipos
def parse_config(path: str) -> Result[Config, ConfigError]:
    try:
        return Result(value=Config.from_file(path))
    except ConfigError as e:
        return Result(error=e)


…