Padronizar tratamento de erros: Substituir None por ValueError em funções de validação/formatação

[niltonpimentel02]

Seu pedido de recurso está relacionado a um problema?

• Em funções que retornam None para entradas inválidas (ex.: brutils/cpf.py::format_cpf), o feedback é genérico e não informa o motivo da falha, dificultando a depuração e o tratamento de erros específico por parte do consumidor da API.

---

Descreva a solução que você gostaria

• Padronizar o tratamento de entradas inválidas, substituindo retornos None por um ValueError genérico (ou TypeError se o tipo estiver incorreto). A exceção deve incluir uma mensagem clara sobre o motivo da invalidez. Atualizar docstrings e type hints para refletir o novo contrato.

---

Descreva alternativas que você considerou

• Manter None com logs: o erro ainda é silencioso para o código chamador e exige checagem manual.
• Retornar False: não fornece contexto sobre o erro.

---

Contexto adicional

• Arquivo: https://github.com/brazilian-utils/python/blob/main/brutils/cpf.py (ex.: format_cpf), e revisar padrões similares em outros módulos (CEP, CNPJ, Placa, PIS).
• Proposta concreta:
  • Lançar ValueError("CPF inválido: formato incorreto ou dígitos de verificação inválidos.") em vez de retornar None.
• Benefícios: feedback imediato e explícito sobre a falha, tratamento de erro padronizado via exceções e maior clareza no fluxo de controle.

[hewerthomn]

bora!

[github-actions]

🇧🇷 Português
✅ Issue #627 atribuída a @hewerthomn. Verifique o guia de contribuição para instruções sobre como submeter sua Pull Request.

🇬🇧 English
✅ Issue #627 assigned to @hewerthomn. Check the contributing guide for instructions on submitting your Pull Request.