Skip to content

README_EN.md

Latest commit

 

History

History
139 lines (101 loc) · 5.92 KB

README_EN.md

File metadata and controls

139 lines (101 loc) · 5.92 KB

ENGLISH | PORTUGUÊS

🐍 PyFlunt: Domain Notification Pattern

Python implementation of Domain Notification Pattern inspired by Flunt (.NET)

Latest Release on PyPI Python Versions Downloads License: MIT Discord Gitter

Avaliação de Segurança Avaliação de Confiabilidade Avaliação de Manutenibilidade Bugs Vulnerabilidades Code Smells

Flunt is a way to implement a notification pattern in your application to centralize errors and changes in certain actions and entities.

Flunt was born out of two needs: implementing the Domain Notification Pattern to replace domain-level exceptions in the application and reducing the amount of IFs (complexity) by using a contract-based approach.

Thus, basically what Flunt does is add a list of Notifications to your class and various methods to interact with it.

✨ Highlights

  • Python 3.11+ compatible with no runtime dependencies.
  • Fluent, chainable validations built on the Domain Notification Pattern.
  • Specialized contracts for numbers, datetime, URLs, and Brazilian documents (CPF/CNPJ).
  • Centralized notifications via Notifiable, reducing scattered if checks and domain exceptions.
  • Full documentation in docs/ and on the site (link below).

New validation contracts

Beyond the base contract, the library now includes specialized contracts for common scenarios:

  • NumericValidationContract for numeric values (ranges, limits, sign)
  • DateTimeValidationContract for datetime values (intervals, minimum/maximum)
  • UrlValidationContract for URLs
  • BrazilianDocumentValidationContract for Brazilian documents (CPF/CNPJ)

Check the docs in docs/validations/ for detailed examples.

➡️ How to use

🔑 Requirements

  • Python 3.11 or newer
  • No runtime dependencies (optional dev tooling: uv, ruff, mypy, pytest)

🔧 Installation

pip install flunt

🔔 Notifiable

from flunt.notifications.notifiable import Notifiable

class Name(Notifiable):
    def __init__(self, name):
        super().__init__()

        if len(name) < 3:
            self.add_notification(
                field='name', message='Name must have at least 3 characters'
            )
        self._name = name

📜 Contract

"""Module Value Objects."""
from flunt.notifications.notifiable import Notifiable
from flunt.validations.contract import Contract


class Name(Notifiable):
    """Class Value Object Name."""

    def __init__(self, first_name, last_name):
        """Found 'Constructor'."""
        super().__init__()
        self.first_name = first_name
        self.last_name = last_name
        self.add_notifications(
            Contract()
            .requires(self.first_name, 'first name', 'First name is required')
            .requires(self.last_name, 'last name', 'Last name is required')
            .is_greater_than(
                value=self.first_name,
                comparer=3,
                field="first_name",
                message="Minimum of 3 characters",
            )
            .is_greater_than(
                value=self.last_name,
                comparer=3,
                field="last_name",
                message="Minimum of 3 characters",
            )
            .get_notifications()
        )


nome = Name('Emerson', 'Delatorre')
if not nome.is_valid:
    for notification in nome.get_notifications():
        print(notification)

Contributing

Please refer to our DevGuide at the following link: CONTRIBUTING

📚 Documentation

Changelog

Please refer to our changelog at the following link: CHANGELOG

📄 License

This project contains the MIT license. See the file LICENSE.

Mods