Skip to content

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

Closed

Description

@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.

Activity

  1. hewerthomn commented on Oct 27, 2025

    @hewerthomn

    bora!

  2. github-actions commented on Oct 27, 2025

    @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.

  3. github-actions commented on Dec 12, 2025

    @github-actions

    📌 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.

  4. niltonpimentel02 commented on Dec 12, 2025

    @niltonpimentel02
    MemberAuthor

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

    #671

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions