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[bot]]

🇧🇷 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.

[github-actions[bot]]

📌 Esta mensagem está tanto em português quanto em inglês (mais abaixo) — assim todo mundo consegue acompanhar! 📌 This message is in both Portuguese and English (further down) — so everyone can follow along!

🇧🇷 Português

👋 Olá!

Esta issue está obsoleta porque ficou aberta por 45 dias sem atividade. Remova o rótulo de stale ou comente, caso contrário ela será fechada em 15 dias.

🇬🇧 English

Hey there! 👋

This issue is stale because it has been open 45 days with no activity. Remove stale label or comment or this will be closed in 15 days.

[niltonpimentel02]

fechado até a gente discutir melhor a solução nesse link:

https://github.com/brazilian-utils/python/discussions/671