simple-value-object 3.3

A simple library to create Value Objects

Value Object

Based on Ruby Gem by NoFlopSquad

A value object is a small object that represents a simple entity whose equality isn't based on identity: i.e. two value objects are equal when they have the same value, not necessarily being the same object.

Wikipedia

New version 3.x

This new version is a complete rewrite of the library, now it uses data classes to define the value objects. With this change we can use type hints to define the fields and the library will take care of the rest. Now you have autocomplete and type checking in your IDE. With the previous version, you did no autocomplete or type-checking. You should be able to use this library with any version of Python 3.7 or higher.

Installation

pip install simple-value-object

Usage

Constructor and field readers

from simple_value_object import ValueObject

class Point(ValueObject):
    x: int
    y: int

point = Point(1, 2)

point.x
# 1

point.y
# 2

point.x = 5
# CannotBeChanged: You cannot change values from a Value Object, create a new one

class Date(ValueObject):
    day: int
    month: int
    year: int

date = Date(1, 10, 2015)

date.day
# 1

date.month
# 10

date.year
# 2015

date.month = 5
# CannotBeChanged: You cannot change values from a Value Object, create a new one

Equality based on field values

from simple_value_object import ValueObject

class Point(ValueObject):
    x: int
    y: int


a_point = Point(5, 3)

same_point = Point(5, 3)

a_point == same_point
# True

a_different_point = Point(6, 3)

a_point == a_different_point
# False

Hash code based on field values

from simple_value_object import ValueObject

class Point(ValueObject):
    x: int
    y: int

a_point = Point(5, 3)

same_point = Point(5, 3)

a_point.hash == same_point.hash
# True

a_different_point = Point.new(6, 3)

a_point.hash == a_different_point.hash
# False

Invariants

Invariants must return a boolean value.

from simple_value_object import ValueObject, invariant

class Point(ValueObject):
    x: int
    y: int

    @invariant
    def inside_first_quadrant(self):
        return self.x > 0 and self.y > 0

    @invariant
    def x_lower_than_y(self):
        return self.x < self.y

Point(-5, 3)
#InvariantViolation: inside_first_cuadrant

Point(6, 3)
#InvariantViolation: x_lower_than_y

Point(1,3)
#<__main__.Point at 0x7f2bd043c780>

Custom exceptions for invariants

You can throw custom exceptions when an invariant is violated and also return the message of the exception that will be raised.

from simple_value_object import ValueObject, invariant

class MyException(Exception):
    pass


class Point(ValueObject):
    x: int
    y: int

    @invariant(exception_type=MyException)
    def inside_first_quadrant(self):
        return self.x > 0 and self.y > 0, "You must be inside the first quadrant"

    @invariant(MyException)
    def x_lower_than_y(self):
        return self.x < self.y, "X must be lower than Y"

Point(-5, 3)
#MyException: "You must be inside the first quadrant"

ValueObject within ValueObject

from simple_value_object import ValueObject, invariant

class Currency(ValueObject):
    symbol: str

class Money(ValueObject):
    amount: Decimal
    currency: Currency

Money(amount=Decimal("100"), currency=Currency(symbol="€"))

Tests

docker/test