feat: Lança ValueError em utilitários de formatação quando o input é inválido

[hewerthomn]

Descrição

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.

Mudanças Propostas

Altera os utilitários format_cpf, format_cnpj, format_cep, format_license_place e format_pis para lançar ValueError quando input for inválido.

Checklist de Revisão

• Eu li o Contributing.md
• Os testes foram adicionados ou atualizados para refletir as mudanças (se aplicável).
• Foi adicionada uma entrada no changelog / Meu PR não necessita de uma nova entrada no changelog.
• A documentação em português foi atualizada ou criada, se necessário.
• Se feita a documentação, a atualização do arquivo em inglês.
• Eu documentei as minhas mudanças no código, adicionando docstrings e comentários. Instruções
• O código segue as diretrizes de estilo e padrões de codificação do projeto.
• Todos os testes passam. Instruções
• O Pull Request foi testado localmente. Instruções
• Não há conflitos de mesclagem.

Comentários Adicionais (opcional)

Issue Relacionada

Closes #627

[niltonpimentel02]

@hewerthomn boa tarde, tudo bem? consegue resolver os conflitos pra gente dar andamento no review?

[hewerthomn]

@niltonpimentel02 boa tarde, resolvi os conflitos

[niltonpimentel02]

boa noite @hewerthomn assim que possível vou revisar o teu pr.. como isso vai gerar um release de breaking changes preciso verificar com um pouco mais de calma.

cc: @morais90 se conseguir me dar um help nesse review seria ótimo

[morais90]

Show ein! Eu gosto dessa ideia de lançar o ValueError, traz vários benefícios (evita erros silenciosos, não deixa que problemas passem para frente no código, e não mistura quando realmente retornar None é um dado válido) para quem utiliza a lib, mas de fato é um breaking change.

A não ser que utilizemos uma abordagem tipo do módulo cep.py com um booleano raise_exceptions (não acho muito clean)...

[hewerthomn]

@niltonpimentel02 e @morais90 considerando que teria o breaking change da api e que usar o parâmetro raise exceptions tbm não fica muito clean,

o que acham da opção de poder ler esse raise exceptions de uma função brutils.configure(raise_exceptions=True) ou até como ler essa config do env com BRUTILS_RAISE_EXCEPTIONS, por exemplo?

Aí na próxima major mudaria o raise exceptions padrão para True, aí quem quiser o comportamento antigo usaria brutils.configure(raise_exceptions=False) sem ter tanto prejuízo

[niltonpimentel02]

fala @hewerthomn tudo bem? primeiramente já vou te pedir desculpas porque conversando com o time sobre essa issue acabei descobrindo que não levei em conta alguns fatores que vão impactar lá na ponta quem tá usando o nosso pacote.. eu sei que é complicado fazer algo e acabar sendo descartado mas espero que isso não te desistumule a contribuir aqui no projeto, visto que, foi um erro meu a abertura dessa issue.

segundamente resolvi criar uma RFC pra gente discutir em conjunto qual seria a melhor opção pra fazer essa migração e te convido pra dar uma olhada e contribuir aqui:

#671

vou fechar esse teu pr juntamente com a issue pra não gerar conflitos com essa nova discussão sobre o assunto.

agradeço demais pela tua contribuição e paciência 💜

[hewerthomn]

Tudo bem @niltonpimentel02, entendo a situação

fico feliz em ter contribuído com o projeto, foi uma experiência e fiz participando da sprint lá da Python Brasil 2025 😄

olhei a RFC e faz muito sentido como está sendo pensada para abranger o projeto
vocês estão de parabéns 👏

valeu