Type Hints - C-Suite
Este documento descreve o padrão de type hints para o ecossistema C-Suite.
Visão Geral
Type hints melhoram legibilidade, facilitam IDEs e permitem verificação estática com mypy.
Configuração
mypy
Configurado em pyproject.toml:
[tool.mypy]
python_version = "3.9"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = false
ignore_missing_imports = true
Verificação
mypy common/
Padrões
Funções Básicas
def add(a: int, b: int) -> int:
return a + b
Funções com Optional
from typing import Optional
def get_user(user_id: int) -> Optional[dict]:
if user_id > 0:
return {"id": user_id}
return None
Funções com Listas
from typing import List
def get_policies(org_id: int) -> List[dict]:
return [{"id": 1}, {"id": 2}]
Funções com Dict
from typing import Dict, Any
def create_policy(data: Dict[str, Any]) -> Dict[str, Any]:
return {"id": 1, **data}
Funções Assíncronas
from typing import Awaitable
async def fetch_data(url: str) -> Awaitable[dict]:
# Async operation
return {"data": "result"}
Classes
from typing import Optional
class Policy:
def __init__(self, org_id: int, rule_key: str, value: float):
self.org_id: int = org_id
self.rule_key: str = rule_key
self.value: float = value
def update(self, new_value: float) -> None:
self.value = new_value
def get_value(self) -> Optional[float]:
return self.value
Generics
from typing import TypeVar, Generic, List
T = TypeVar('T')
class Cache(Generic[T]):
def __init__(self):
self._items: List[T] = []
def add(self, item: T) -> None:
self._items.append(item)
def get(self, index: int) -> Optional[T]:
if 0 <= index < len(self._items):
return self._items[index]
return None
Callables
from typing import Callable
def apply_function(func: Callable[[int], int], value: int) -> int:
return func(value)
Union Types
from typing import Union
def process_value(value: Union[int, str]) -> str:
return str(value)
Exemplos por Módulo
common_db_pool.py
from typing import Optional, Dict
from sqlalchemy.engine import Engine
def get_db_engine(
database: str = "csuite",
pool_config: Optional[PoolConfig] = None
) -> Engine:
# Implementation
pass
common_notifications.py
from typing import Optional, Dict, Any
from enum import Enum
def send_notification(
title: str,
message: str,
priority: NotificationPriority = NotificationPriority.MEDIUM,
channel: NotificationChannel = NotificationChannel.EMAIL,
recipient: Optional[str] = None,
metadata: Optional[Dict[str, Any]] = None
) -> bool:
# Implementation
pass
Migração Gradual
Estratégia
- Novo código: Sempre usar type hints
- Código existente: Adicionar gradualmente
- APIs públicas: Prioridade alta
- Código interno: Prioridade média
Checklist
- [ ] Funções públicas têm type hints
- [ ] Classes têm type hints
- [ ] mypy passa sem erros críticos
- [ ] Documentação atualizada