PORTUGUÊS | ENGLISH

🐍 PyFlunt: Domain Notification Pattern

Implementação Python inspirada no Flunt (.NET)

Flunt te auxilia a implementar Domain Notification Pattern em sua aplicação para centralizar erros e mudanças em determinadas ações e entidades.

Flunt surgiu de duas necessidades: implementar o Domain Notification Pattern para substituir exceções no nível de domínio da aplicação e reduzir a quantidade de IFs (complexidade) usando uma abordagem baseada em contratos.

Assim, basicamente o que o Flunt faz é adicionar uma lista de Notificações à sua classe e vários métodos para interagir com ela.

✨ Destaques

• Compatível com Python 3.11+ e sem dependências de runtime.
• Validações fluentes encadeáveis baseadas no Domain Notification Pattern.
• Contratos especializados para números, datas/horas, URLs e documentos brasileiros (CPF/CNPJ).
• Notificações centralizadas via Notifiable, evitando ifs espalhados e exceções de domínio.
• Documentação completa em docs/ e no site (link abaixo).

Novos contratos de validação

Além do contrato base, a biblioteca agora inclui contratos especializados para cenários comuns:

• NumericValidationContract para valores numéricos (faixas, limites, sinal)
• DateTimeValidationContract para datas/horas (intervalos, mínimos/máximos)
• UrlValidationContract para URLs
• BrazilianDocumentValidationContract para documentos brasileiros (CPF/CNPJ)

Consulte a documentação em docs/validations/ para exemplos detalhados.

➡️ Como usar

🔑 Requisitos

• Python 3.11 ou superior
• Sem dependências de runtime (ferramentas de dev opcionais: uv, ruff, mypy, pytest)

🔧 Instalação

pip install flunt

🔔 Notifiable

O Notifiable é a classe base que fornece funcionalidades para armazenar e gerenciar notificações:

from flunt.notifications.notifiable import Notifiable

class Nome(Notifiable):
    def __init__(self, nome):
        super().__init__()

        if len(nome) < 3:
            self.add_notification(
                field='nome',
                message='Nome deve ter pelo menos 3 caracteres',
            )
        self._nome = nome

📜 Contract

O Contract fornece métodos para validações encadeadas:

"""Módulo de exemplo com Objetos de Valor."""
from flunt.notifications.notifiable import Notifiable
from flunt.validations.contract import Contract


class Pessoa(Notifiable):
    """Classe Objeto de Valor Pessoa."""

    def __init__(self, primeiro_nome, ultimo_nome, email):
        """Construtor da classe."""
        super().__init__()
        self.primeiro_nome = primeiro_nome
        self.ultimo_nome = ultimo_nome
        self.email = email

        # Criando um contrato de validação
        contract = (
            Contract()
            .requires(self.primeiro_nome, "primeiro nome", "Nome é obrigatório")
            .requires(self.ultimo_nome, "ultimo nome", "Sobrenome é obrigatório")
            .requires(self.email, "email", "E-mail é obrigatório")
            .is_lower_than(
                self.primeiro_nome,
                3,
                "primeiro_nome",
                "Nome deve ter no mínimo 3 caracteres",
            )
            .is_lower_than(
                self.ultimo_nome,
                3,
                "ultimo_nome",
                "Sobrenome deve ter no mínimo 3 caracteres",
            )
            .is_email(self.email, "email", "E-mail inválido")
        )

        # Adicionando as notificações do contrato à entidade
        self.add_notifications(contract.get_notifications())


# Exemplo de uso
pessoa = Pessoa("Alfredo", "Biscoito", "alfredo@biscoito.com")
if not pessoa.is_valid:
    for notification in pessoa.get_notifications():
        print(notification)
else:
    print("Validado com sucesso!")

Contribuindo

Consulte nosso DevGuide no link a seguir: CONTRIBUTING

📚 Documentação

• Site (MkDocs): https://fazedordecodigo.github.io/PyFlunt/
• Arquivos locais: docs/

Registro de Alterações

Consulte nosso registro de alterações no link a seguir: CHANGELOG

📄 Licença

Este projeto contém a licença MIT. Consulte o arquivo LICENSE.

Mods

• Flunt para C# (Original)
• Flunt.Br
• Flunt para Java
• Flunt para JavaScript
• Flunt para PHP