Contexto

Hoje, várias funções do brutils retornam None quando recebem valores inválidos.
Alguns exemplos (extraídos da documentação):

• format_cpf(...) → retorna str ou None se o CPF é inválido.
• format_cnpj(...) → retorna str ou None se o CNPJ é inválido.
• format_cep(...) → retorna str ou None se o CEP é inválido.
• format_phone(...) → retorna str ou None se o telefone é inválido.
• Diversas outras funções de formatação e conversão seguem esse padrão.

Objetivo

• Definir uma estratégia padronizada para tratamento de valores inválidos nas funções do brazilian-utils.
• Preferencialmente, alinhar com a prática Python de levantar exceções quando o input é inválido.
• Fazer isso de forma:
  • bem documentada,
  • previsível para quem usa a lib,
  • com um caminho de migração suave e incremental,
  • sem quebrar código existente até uma major release.

Proposta de abordagem

Estratégia: Strict Mode Global + Parâmetro strict por função + Decorador @strictify

Esta abordagem combina três níveis de controle:

1. Strict mode global — ativa/desativa o comportamento estrito para toda a lib
2. Parâmetro strict por função — permite controle granular por chamada
3. Decorador @strictify — centraliza a lógica de decisão e permite migração incremental

Prioridade de comportamento

O decorador @strictify decide se deve levantar exceção seguindo esta ordem:

1. Se strict=True foi passado na função → levanta exceção
2. Se strict=False foi passado na função → retorna None (comportamento legado)
3. Se strict não foi passado, verifica o strict mode global:
   • Se strict_mode_enabled() → levanta exceção
   • Caso contrário → retorna None (comportamento legado)

Componentes da solução

1. Hierarquia de exceções customizadas

class BrutilsError(Exception):
 """Exceção base para todos os erros do brutils."""
 pass
class InvalidCPFError(BrutilsError):
 """Levantada quando um CPF inválido é fornecido."""
 pass
class InvalidCNPJError(BrutilsError):
 """Levantada quando um CNPJ inválido é fornecido."""
 pass
class InvalidCEPError(BrutilsError):
 """Levantada quando um CEP inválido é fornecido."""
 pass
# ... outras exceções específicas

2. Strict mode global

_STRICT_MODE = False
def enable_strict_mode() -> None:
 """Ativa o strict mode globalmente para todas as funções do brutils."""
 global _STRICT_MODE
 _STRICT_MODE = True
def disable_strict_mode() -> None:
 """Desativa o strict mode globalmente."""
 global _STRICT_MODE
 _STRICT_MODE = False
def strict_mode_enabled() -> bool:
 """Retorna True se o strict mode está ativo globalmente."""
 return _STRICT_MODE

3. Decorador @strictify

def strictify(func):
 def wrapper(*args, **kwargs):
 try:
 return func(*args, **kwargs)
 except Exception as e:
 if strict_mode_enabled() or kwargs.get("strict"):
 raise # novo comportamento
 return None # comportamento legado
 return wrapper

4. Adicionar warnings sobre futura mudança de default

import warnings
def format_cpf(cpf: str, *, strict: bool | None = None) -> str:
 if strict is None and not strict_mode_enabled():
 warnings.warn(
 "O comportamento padrão de format_cpf mudará na v3.0.0. "
 "CPFs inválidos levantarão InvalidCPFError ao invés de retornar None. "
 "Use strict=False para manter o comportamento atual.",
 DeprecationWarning,
 stacklevel=2
 )
 # ... resto da função

Resultado: Usuários são avisados com antecedência sobre a mudança futura.

Vantagens desta abordagem

✅ Não força usuários atuais a mudar nada — comportamento legado preservado até v3.0.0

✅ Permite evolução incremental da lib — migrar 1 função por vez, sem pressa

✅ Introduz comportamento mais seguro sem atrito — usuários podem adotar quando quiserem

✅ Granularidade total — controle global E por função

✅ Alinhado com práticas de grandes libs Python — Django, Pydantic, SQLAlchemy, Requests, Boto3 usam estratégias similares

✅ Facilita testes e code review — mudanças pequenas e incrementais

✅ Tipagem estática melhorada — funções em strict mode podem retornar str ao invés de str | None

Tarefas de implementação

Fase 1: Infraestrutura

• Criar módulo brutils/exceptions.py com hierarquia de exceções
• Implementar strict mode global em brutils/__init__.py
• Implementar decorador @strictify
• Adicionar testes para infraestrutura
• Documentar no README.md e README_EN.md

Fase 2: Migração incremental

• Migrar format_cpf e is_valid_cpf
• Migrar format_cnpj e is_valid_cnpj
• Migrar format_cep e is_valid_cep
• Migrar demais utilitários

Alternativas Consideradas

Usar ValueError padrão ao invés de exceções customizadas

Descrição:

Ao invés de criar uma hierarquia de exceções customizadas (BRUtilsError, InvalidCPFError, etc.), usar apenas ValueError do Python padrão.

Exemplo:

@strictify
def format_cpf(cpf: str, *, strict: bool | None = None) -> str:
 """
 Formata um CPF válido.

 Raises:
 ValueError: Se o CPF é inválido e strict mode está ativo
 """
 if not is_valid_cpf(cpf):
 raise ValueError(f"Invalid CPF: {cpf}")
 
 return cpf_formatado

Perguntas para discussão

1. Vocês concordam com essa abordagem de migração incremental + strict mode global + parâmetro granular?

2. A ordem de prioridade (parâmetro strict > modo global > legado) faz sentido?

3. Os nomes escolhidos estão adequados?

   • enable_strict_mode() / disable_strict_mode() / strict_mode_enabled()
   • Parâmetro strict (ao invés de raise_exceptions)
   • Decorador @strictify
   • Exceções como InvalidCPFError, InvalidCNPJError, etc.

4. Existe alguma função específica onde esse modelo não se aplica bem?