# Value Object
  
Based on Ruby Gem by [NoFlopSquad](https://github.com/noflopsquad/value-object)
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](http://en.wikipedia.org/wiki/Value_object)
## 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
```sh
pip install simple-value-object
```
## Usage
### Constructor and field readers
```python
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
```python
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
```python
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.
```python
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.
```python
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
```python
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
```sh
docker/test
```
Raw data
{
"_id": null,
"home_page": "https://github.com/quiqueporta/value-object",
"name": "simple-value-object",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "python, ddd",
"author": "Quique Porta",
"author_email": "me@quiqueporta.com",
"download_url": "https://files.pythonhosted.org/packages/24/cc/a7ccdf37e58df0fc9e51ecf436cede982b073756e2281bd6f6ef0404b171/simple-value-object-3.3.tar.gz",
"platform": null,
"description": "# Value Object\n\n  \n\nBased on Ruby Gem by [NoFlopSquad](https://github.com/noflopsquad/value-object)\n\nA **value object** is a small object that represents a simple entity whose equality isn't based on identity:\ni.e. two value objects are equal when they have the same value, not necessarily being the same object.\n\n[Wikipedia](http://en.wikipedia.org/wiki/Value_object)\n\n## New version 3.x\n\nThis new version is a complete rewrite of the library, now it uses data classes to define the value objects.\nWith this change we can use type hints to define the fields and the library will take care of the rest.\nNow you have autocomplete and type checking in your IDE. With the previous version, you did no autocomplete or type-checking.\nYou should be able to use this library with any version of Python 3.7 or higher.\n\n## Installation\n\n```sh\npip install simple-value-object\n```\n\n## Usage\n\n### Constructor and field readers\n\n```python\nfrom simple_value_object import ValueObject\n\nclass Point(ValueObject):\n x: int\n y: int\n\npoint = Point(1, 2)\n\npoint.x\n# 1\n\npoint.y\n# 2\n\npoint.x = 5\n# CannotBeChanged: You cannot change values from a Value Object, create a new one\n\nclass Date(ValueObject):\n day: int\n month: int\n year: int\n\ndate = Date(1, 10, 2015)\n\ndate.day\n# 1\n\ndate.month\n# 10\n\ndate.year\n# 2015\n\ndate.month = 5\n# CannotBeChanged: You cannot change values from a Value Object, create a new one\n```\n\n### Equality based on field values\n\n```python\nfrom simple_value_object import ValueObject\n\nclass Point(ValueObject):\n x: int\n y: int\n\n\na_point = Point(5, 3)\n\nsame_point = Point(5, 3)\n\na_point == same_point\n# True\n\na_different_point = Point(6, 3)\n\na_point == a_different_point\n# False\n```\n\n### Hash code based on field values\n\n```python\nfrom simple_value_object import ValueObject\n\nclass Point(ValueObject):\n x: int\n y: int\n\na_point = Point(5, 3)\n\nsame_point = Point(5, 3)\n\na_point.hash == same_point.hash\n# True\n\na_different_point = Point.new(6, 3)\n\na_point.hash == a_different_point.hash\n# False\n```\n\n### Invariants\n\nInvariants **must** return a boolean value.\n\n```python\nfrom simple_value_object import ValueObject, invariant\n\nclass Point(ValueObject):\n x: int\n y: int\n\n @invariant\n def inside_first_quadrant(self):\n return self.x > 0 and self.y > 0\n\n @invariant\n def x_lower_than_y(self):\n return self.x < self.y\n\nPoint(-5, 3)\n#InvariantViolation: inside_first_cuadrant\n\nPoint(6, 3)\n#InvariantViolation: x_lower_than_y\n\nPoint(1,3)\n#<__main__.Point at 0x7f2bd043c780>\n\n```\n\n#### Custom exceptions for invariants\n\nYou can throw custom exceptions when an invariant is violated and also return the message of\nthe exception that will be raised.\n\n```python\n\nfrom simple_value_object import ValueObject, invariant\n\nclass MyException(Exception):\n pass\n\n\nclass Point(ValueObject):\n x: int\n y: int\n\n @invariant(exception_type=MyException)\n def inside_first_quadrant(self):\n return self.x > 0 and self.y > 0, \"You must be inside the first quadrant\"\n\n @invariant(MyException)\n def x_lower_than_y(self):\n return self.x < self.y, \"X must be lower than Y\"\n\nPoint(-5, 3)\n#MyException: \"You must be inside the first quadrant\"\n```\n\n### ValueObject within ValueObject\n\n```python\nfrom simple_value_object import ValueObject, invariant\n\nclass Currency(ValueObject):\n symbol: str\n\nclass Money(ValueObject):\n amount: Decimal\n currency: Currency\n\nMoney(amount=Decimal(\"100\"), currency=Currency(symbol=\"\u20ac\"))\n```\n\n## Tests\n\n```sh\ndocker/test\n```\n\n\n",
"bugtrack_url": null,
"license": "MIT/X11",
"summary": "A simple library to create Value Objects",
"version": "3.3",
"project_urls": {
"Download": "https://github.com/quiqueporta/simple-value-object/releases",
"Homepage": "https://github.com/quiqueporta/value-object"
},
"split_keywords": [
"python",
" ddd"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "24cca7ccdf37e58df0fc9e51ecf436cede982b073756e2281bd6f6ef0404b171",
"md5": "bc5702937630469700b9972c0b588a26",
"sha256": "85ba342a8cf2487ff671258bb6421e0e4a736c2b83df047ea365b3e45a1a01c2"
},
"downloads": -1,
"filename": "simple-value-object-3.3.tar.gz",
"has_sig": false,
"md5_digest": "bc5702937630469700b9972c0b588a26",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 5067,
"upload_time": "2024-05-25T18:03:59",
"upload_time_iso_8601": "2024-05-25T18:03:59.890475Z",
"url": "https://files.pythonhosted.org/packages/24/cc/a7ccdf37e58df0fc9e51ecf436cede982b073756e2281bd6f6ef0404b171/simple-value-object-3.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-25 18:03:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "quiqueporta",
"github_project": "value-object",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "simple-value-object"
}
JSON
