📝 Guia de Type Hints - C-Suite

Data: 2025-12-01
Status: ✅ Em Progresso

🎯 Objetivo

Adicionar type hints gradualmente em todo o código Python para melhorar:
- Legibilidade - Fica claro quais tipos são esperados
- Manutenibilidade - IDEs podem fornecer melhor autocomplete
- Detecção de Erros - mypy pode detectar erros antes da execução
- Documentação - Type hints servem como documentação inline

📋 Estratégia de Implementação

Fase 1: Módulos Comuns (Em Progresso)

✅ Adicionar type hints em funções públicas
✅ Adicionar type hints em classes e métodos
✅ Usar Optional para valores que podem ser None
✅ Usar Union para múltiplos tipos possíveis

Fase 2: Apps Principais

⏳ Adicionar type hints em endpoints FastAPI
⏳ Adicionar type hints em funções de negócio
⏳ Adicionar type hints em modelos Pydantic

Fase 3: Código Legado

⏳ Migrar código existente gradualmente
⏳ Priorizar código crítico primeiro

🔧 Ferramentas

mypy

Configuração: pyproject.toml
Modo: Opcional no CI/CD (não falha o pipeline)
Comando: mypy common/ --ignore-missing-imports --no-strict-optional

Type Checking no CI/CD

Executado no GitHub Actions (opcional)
Não falha o pipeline se houver erros
Pode ser habilitado como obrigatório quando type hints estiverem completos

📚 Padrões de Type Hints

Funções Básicas

from typing import Optional, List, Dict, Any, Union

def get_user(user_id: int) -> Optional[Dict[str, Any]]:
    """Retorna usuário ou None se não encontrado"""
    ...

def process_items(items: List[str]) -> List[Dict[str, Any]]:
    """Processa lista de itens"""
    ...

def create_config(name: str, debug: bool = False) -> Dict[str, Any]:
    """Cria configuração"""
    ...

Funções Assíncronas

from typing import Awaitable, Coroutine

async def fetch_data(url: str) -> Dict[str, Any]:
    """Busca dados de uma URL"""
    ...

async def process_async(items: List[str]) -> List[Dict[str, Any]]:
    """Processa itens assincronamente"""
    ...

Classes e Métodos

from typing import Optional, List

class UserService:
    def __init__(self, db_url: str) -> None:
        self.db_url = db_url

    def get_user(self, user_id: int) -> Optional[Dict[str, Any]]:
        """Retorna usuário"""
        ...

    @classmethod
    def create(cls, name: str) -> "UserService":
        """Cria nova instância"""
        ...

Optional e Union

from typing import Optional, Union

def parse_value(value: Union[str, int]) -> Optional[int]:
    """Converte valor para int ou retorna None"""
    if isinstance(value, int):
        return value
    try:
        return int(value)
    except ValueError:
        return None

Generics

from typing import TypeVar, Generic, List

T = TypeVar('T')

class Cache(Generic[T]):
    def get(self, key: str) -> Optional[T]:
        ...

    def set(self, key: str, value: T) -> None:
        ...

Callables

from typing import Callable, List

def process_with_callback(
    items: List[str],
    callback: Callable[[str], bool]
) -> List[str]:
    """Processa itens com callback"""
    return [item for item in items if callback(item)]

✅ Checklist de Type Hints

Para Cada Função

[ ] Parâmetros têm type hints
[ ] Valor de retorno tem type hint
[ ] None é explicitado com Optional
[ ] Múltiplos tipos usam Union
[ ] Listas/Dicts têm tipos de elementos especificados

Para Cada Classe

[ ] __init__ tem type hints
[ ] Métodos têm type hints
[ ] Propriedades têm type hints
[ ] Métodos de classe usam @classmethod com type hints

Para Cada Módulo

[ ] Imports de typing estão presentes
[ ] Type hints estão consistentes
[ ] mypy não reporta erros (quando possível)

🚫 Erros Comuns

❌ Evitar

# Sem type hints
def process(data):
    return data.items()

# Type hints incompletos
def process(data: dict) -> dict:
    return data.items()

# Usar Any desnecessariamente
def process(data: Any) -> Any:
    return data.items()

✅ Preferir

# Type hints completos
def process(data: Dict[str, Any]) -> List[Tuple[str, Any]]:
    return list(data.items())

# Específico quando possível
def get_user_id(user: Dict[str, Any]) -> int:
    return user["id"]

📊 Progresso

Módulos Comuns

✅ common_environments.py - Type hints adicionados
⏳ common_validation.py - Parcial
⏳ common_logging.py - Parcial
⏳ common_errors.py - Parcial
⏳ Outros módulos - Em progresso

Apps

⏳ 4c-suite - Pendente
⏳ csuite-executive - Pendente
⏳ 4c/api/* - Pendente

🎯 Próximos Passos

✅ Adicionar type hints em common_environments.py
⏳ Adicionar type hints em outros módulos comuns críticos
⏳ Habilitar mypy como obrigatório no CI/CD quando type hints estiverem completos
⏳ Adicionar type hints em código novo automaticamente
⏳ Migrar código legado gradualmente

📚 Recursos

Última atualização: 2025-12-01

Type Hints Guide