# Sutoppu
[](https://pypi.org/project/sutoppu/)
[](https://pypi.org/project/sutoppu/)
[](https://github.com/u8slvn/sutoppu/actions/workflows/ci.yml)
[](https://coveralls.io/github/u8slvn/sutoppu?branch=master)
[](https://pypi.org/project/sutoppu/)
[](https://github.com/psf/black)
**Sutoppu** (ในใใใ - Japanese from English *Stop*) is a simple python implementation of Specification pattern.
## What is Specification Pattern?
See [Wikipedia](https://en.wikipedia.org/wiki/Specification_pattern).
> In computer programming, the specification pattern is a particular software design pattern, whereby business rules can be recombined by chaining the business rules together using boolean logic. The pattern is frequently used in the context of domain-driven design.
More information: [Eric Evans and Martin Fowler article about Specifications](https://www.martinfowler.com/apsupp/spec.pdf)
## Basic usage
### Installation
```sh
$ pip install sutoppu
```
### Usage
```python
from sutoppu import Specification
class Fruit:
def __init__(self, color: str, sweet: bool, bitter: bool) -> None:
self.color = color
self.sweet = sweet
self.bitter = bitter
class FruitIsBitter(Specification[Fruit]):
description = 'The given fruit must be bitter.'
def is_satisfied_by(self, fruit: Fruit) -> bool:
return fruit.bitter is True
class FruitIsSweet(Specification[Fruit]):
description = 'The given fruit must be sweet.'
def is_satisfied_by(self, fruit: Fruit) -> bool:
return fruit.sweet is True
class FruitIsYellow(Specification[Fruit]):
description = 'The given fruit must be yellow.'
def is_satisfied_by(self, fruit: Fruit) -> bool:
return fruit.color == 'yellow'
```
```python
>>> lemon = Fruit(color='yellow', sweet=False, bitter=True)
>>> is_a_lemon = FruitIsYellow() & FruitIsBitter() & ~FruitIsSweet()
>>> is_a_lemon.is_satisfied_by(lemon)
True
```
### Operators
**Sutoppu** uses bitwise operator overloading to provide simplified syntax.
And:
```python
>>> my_spec = SpecificationA() & SpecificationB()
```
Or:
```python
>>> my_spec = SpecificationA() | SpecificationB()
```
Not:
```python
>>> my_spec = ~SpecificationA()
```
### Lighter syntax
If you find the `is_satisfied_by` method inconvenient you can alternatively call the specification as shown below.
```python
>>> lemon = Fruit(color='yellow', sweet=False, bitter=True)
>>> is_a_lime = FruitIsGreen() & FruitIsBitter() & ~FruitIsSweet()
>>> is_a_lime(lemon)
False
```
### Error reporting
It can be difficult to know which specification failed in complex concatenated rules. Sutoppu allows to list all the failed specifications by getting the `errors` attribute after use.
The `errors` attribute is reset each time the specification is used. For each failed specification, it returns a dict with the name of the specification class as key and the description provided in the class as value. In the case where the specification failed with a `not` condition, the description is prefixed with `Not ~`.
```python
>>> apple = Fruit(color='red', sweet=True, bitter=False)
>>> is_a_lemon = FruitIsYellow() & FruitIsBitter() & ~ FruitIsSweet()
>>> is_a_lemon.is_satisfied_by(apple)
False
>>> is_a_lemon.errors
{
'FruitIsColored': 'The given fruit must be yellow.',
'FruitIsBitter': 'The given fruit must be bitter.',
'FruitIsSweet': 'Not ~ The given fruit must be sweet.'
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/u8slvn/sutoppu",
"name": "sutoppu",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8.1,<4.0.0",
"maintainer_email": "",
"keywords": "specification,specification-pattern,DDD,domain-driven-design,business-rules,verification",
"author": "u8slvn",
"author_email": "u8slvn@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/a8/be/fff7a4dc7eb201b673400d1b333374afd8f74be90f96f46e2d912f485ff4/sutoppu-1.1.0.tar.gz",
"platform": null,
"description": "# Sutoppu\n\n[](https://pypi.org/project/sutoppu/)\n[](https://pypi.org/project/sutoppu/)\n[](https://github.com/u8slvn/sutoppu/actions/workflows/ci.yml)\n[](https://coveralls.io/github/u8slvn/sutoppu?branch=master)\n[](https://pypi.org/project/sutoppu/)\n[](https://github.com/psf/black)\n\n**Sutoppu** (\u30b9\u30c8\u30c3\u30d7 - Japanese from English *Stop*) is a simple python implementation of Specification pattern.\n\n## What is Specification Pattern?\n\nSee [Wikipedia](https://en.wikipedia.org/wiki/Specification_pattern).\n\n> In computer programming, the specification pattern is a particular software design pattern, whereby business rules can be recombined by chaining the business rules together using boolean logic. The pattern is frequently used in the context of domain-driven design.\n\nMore information: [Eric Evans and Martin Fowler article about Specifications](https://www.martinfowler.com/apsupp/spec.pdf)\n\n## Basic usage\n\n### Installation\n\n```sh\n$ pip install sutoppu\n```\n\n### Usage\n\n```python\nfrom sutoppu import Specification\n\n\nclass Fruit:\n def __init__(self, color: str, sweet: bool, bitter: bool) -> None:\n self.color = color\n self.sweet = sweet\n self.bitter = bitter\n\n\nclass FruitIsBitter(Specification[Fruit]):\n description = 'The given fruit must be bitter.'\n\n def is_satisfied_by(self, fruit: Fruit) -> bool:\n return fruit.bitter is True\n\n\nclass FruitIsSweet(Specification[Fruit]):\n description = 'The given fruit must be sweet.'\n\n def is_satisfied_by(self, fruit: Fruit) -> bool:\n return fruit.sweet is True\n\n\nclass FruitIsYellow(Specification[Fruit]):\n description = 'The given fruit must be yellow.'\n\n def is_satisfied_by(self, fruit: Fruit) -> bool:\n return fruit.color == 'yellow'\n```\n\n```python\n>>> lemon = Fruit(color='yellow', sweet=False, bitter=True)\n>>> is_a_lemon = FruitIsYellow() & FruitIsBitter() & ~FruitIsSweet()\n>>> is_a_lemon.is_satisfied_by(lemon)\nTrue\n```\n\n### Operators\n\n**Sutoppu** uses bitwise operator overloading to provide simplified syntax.\n\nAnd:\n\n```python\n>>> my_spec = SpecificationA() & SpecificationB()\n```\n\nOr:\n\n```python\n>>> my_spec = SpecificationA() | SpecificationB()\n```\n\nNot:\n\n```python\n>>> my_spec = ~SpecificationA()\n```\n\n### Lighter syntax\n\nIf you find the `is_satisfied_by` method inconvenient you can alternatively call the specification as shown below.\n\n```python\n>>> lemon = Fruit(color='yellow', sweet=False, bitter=True)\n>>> is_a_lime = FruitIsGreen() & FruitIsBitter() & ~FruitIsSweet()\n>>> is_a_lime(lemon)\nFalse\n```\n\n### Error reporting\n\nIt can be difficult to know which specification failed in complex concatenated rules. Sutoppu allows to list all the failed specifications by getting the `errors` attribute after use.\nThe `errors` attribute is reset each time the specification is used. For each failed specification, it returns a dict with the name of the specification class as key and the description provided in the class as value. In the case where the specification failed with a `not` condition, the description is prefixed with `Not ~`.\n\n```python\n>>> apple = Fruit(color='red', sweet=True, bitter=False)\n>>> is_a_lemon = FruitIsYellow() & FruitIsBitter() & ~ FruitIsSweet()\n>>> is_a_lemon.is_satisfied_by(apple)\nFalse\n>>> is_a_lemon.errors\n{\n 'FruitIsColored': 'The given fruit must be yellow.',\n 'FruitIsBitter': 'The given fruit must be bitter.',\n 'FruitIsSweet': 'Not ~ The given fruit must be sweet.'\n}\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A simple python implementation of Specification pattern.",
"version": "1.1.0",
"project_urls": {
"Homepage": "https://github.com/u8slvn/sutoppu",
"Repository": "https://github.com/u8slvn/sutoppu"
},
"split_keywords": [
"specification",
"specification-pattern",
"ddd",
"domain-driven-design",
"business-rules",
"verification"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d790196ebab199bfe38c7645584a38cafbc9e63cc2d79b3d56f9ffb362a7f4f1",
"md5": "8c1730147a5961da7def304909a5df22",
"sha256": "77a40a1718e104b3163170c7de950a91e5e5c8d5ef83954593979bb29ff7e253"
},
"downloads": -1,
"filename": "sutoppu-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8c1730147a5961da7def304909a5df22",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.1,<4.0.0",
"size": 7715,
"upload_time": "2024-02-02T15:48:43",
"upload_time_iso_8601": "2024-02-02T15:48:43.040947Z",
"url": "https://files.pythonhosted.org/packages/d7/90/196ebab199bfe38c7645584a38cafbc9e63cc2d79b3d56f9ffb362a7f4f1/sutoppu-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a8befff7a4dc7eb201b673400d1b333374afd8f74be90f96f46e2d912f485ff4",
"md5": "c50085c6bb1f892f45a1d60946c08c69",
"sha256": "a04b15b4b308eb01710d23cc76fa47f9946bf4e7e15576e39f5765151e25df5e"
},
"downloads": -1,
"filename": "sutoppu-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "c50085c6bb1f892f45a1d60946c08c69",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8.1,<4.0.0",
"size": 5239,
"upload_time": "2024-02-02T15:48:44",
"upload_time_iso_8601": "2024-02-02T15:48:44.156331Z",
"url": "https://files.pythonhosted.org/packages/a8/be/fff7a4dc7eb201b673400d1b333374afd8f74be90f96f46e2d912f485ff4/sutoppu-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-02 15:48:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "u8slvn",
"github_project": "sutoppu",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "sutoppu"
}
JSON
