Programming by contract library.
Project description
Deal Logo
Deal – python library for design by contract (DbC) programming.
This library contain 3 main conception from DbC:
Precondition – condition that must be true before function is executed.
Postcondition – condition that must be true after function executed.
Invariant – condition that can be relied upon to be true during execution of a program. In this library invariant condition check in 3 cases:
Before class method execution.
After class method execution.
After some class attribute setting.
Features
Functional declaration.
Custom exceptions.
Raising exceptions from contract.
Django Forms styled validators.
Attribute setting invariant validation.
Dynamically assigned attributes and methods invariant validation.
Installation
Stable:
pip install dealDev:
pip install -e git+https://github.com/orsinium/deal.git#egg=dealTL;DR
@pre – validate function arguments (pre-validation).
@post – validate function result (post-validation).
@inv – validate class methods before and after some method calling and after attribute setting.
Exceptions structure:
ContractError (inherited from built-in AssertionError)
PreContractError
PostContractError
InvContractError
Library decorators doesn’t catch any exceptions raised from contracts.
Usage
Contract types
Pre (pre, require):
In [1]: from deal import pre, post, inv, Scheme
In [2]: @pre(lambda *args: all(map(lambda x: x > 0, args)))
...: def my_sum(*args):
...: return sum(args)
...:
In [3]: my_sum(2, 3, 4)
Out[3]: 9
In [4]: my_sum(2, -3, 4)
PreContractError:Post (post, ensure):
In [1]: @post(lambda x: x > 0)
...: def my_sum(*args):
...: return sum(args)
...:
In [2]: my_sum(2, -3, 4)
Out[2]: 3
In [3]: my_sum(2, -3, -4)
PostContractError:Inv (inv, invariant):
In [1]: @inv(lambda obj: obj.x > 0)
...: class A:
...: x = 4
...:
In [2]: a = A()
In [3]: a.x = 10
In [4]: a.x = -10
InvContractError:
In [5]: A
Out[5]: deal.core.AInvariantedCustomize error message
Custom message:
In [1]: @pre(lambda x: x > 0, "x must be > 0")
...: def f(x):
...: return x * 2
...:
In [2]: f(-2)
PreContractError: x must be > 0Custom exception:
In [1]: @pre(lambda x: x > 0, exception=AssertionError("x must be > 0"))
...: def f(x):
...: return x * 2
...:
In [2]: f(-2)
AssertionError: x must be > 0Return error message from contract:
In [1]: @pre(lambda x: x > 0 or "x must be > 0")
...: def f(x):
...: return x * 2
...:
In [2]: f(-5)
PreContractError: x must be > 0Validators
Regular contract with errors returning:
In [1]: def contract(name):
...: if not isinstance(name, str):
...: return "name must be str"
...: return True
...:
In [2]: @pre(contract)
...: def f(x):
...: return x * 2
...:
In [3]: f('Chris')
Out[3]: 'ChrisChris'
In [4]: f(4)
PreContractError: name must be strSimple validator (nearly Django Forms style, except initialization):
In [1]: class Validator:
...: def __init__(self, x):
...: self.x = x
...:
...: def is_valid(self):
...: if self.x <= 0:
...: self.errors = ['x must be > 0']
...: return False
...: return True
...:
In [2]: @pre(Validator)
...: def f(x):
...: return x * 2
...:
In [3]: f(5)
Out[3]: 10
In [4]: f(-5)
PreContractError: ['x must be > 0']Scheme like simple validator but data attribute contains dictionary with all passed arguments:
In [1]: class NameScheme(Scheme):
...: def is_valid(self):
...: if not isinstance(self.data['name'], str):
...: self.errors = ['name must be str']
...: return False
...: return True
...:
In [2]: @pre(NameScheme)
...: def f(name):
...: return name * 2
...:
In [3]: f('Chris')
Out[3]: 'ChrisChris'
In [4]: f(3)
PreContractError: ['name must be str']Scheme automatically detect all arguments names:
In [1]: class Printer(Scheme):
...: def is_valid(self):
...: print(self.data)
...: return True
...:
In [2]: @pre(Printer)
...: def f(a, b, c=4, *args, **kwargs):
...: pass
...:
In [3]: f(1, b=2, e=6)
{'args': (), 'a': 1, 'b': 2, 'c': 4, 'e': 6, 'kwargs': {'e': 6}}
In [4]: f(1, 2, 3, 4, 5, 6)
{'a': 1, 'b': 2, 'c': 3, 'args': (4, 5, 6), 'kwargs': {}}You can use any validators from djburger. See validators documentation and list of supported external libraries. For example, deal + djburger + marshmallow:
In [1]: import djburger, marshmallow
In [2]: class Scheme(djburger.v.b.Marshmallow):
...: name = marshmallow.fields.Str()
...:
In [3]: @pre(Scheme)
...: def func(name):
...: return name * 2
...:
In [4]: func('Chris')
Out[4]: 'ChrisChris'
In [5]: func(123)
PreContractError: {'name': ['Not a valid string.']}Djburger is Django independent. You can use it in any python projects.
Contracts chaining
You can chain any contracts:
In [1]: @pre(lambda x: x > 0)
...: @pre(lambda x: x < 10)
...: def f(x):
...: return x * 2
...:
In [2]: f(5)
Out[2]: 10
In [3]: f(-1)
PreContractError:
In [3]: f(12)
PreContractError:Chaining order:
@inv: from top to bottom.
@pre: from top to bottom.
@post: from bottom to top.
Disable contracts on production
If you want disable contracts on production, pass debug=True to decorator:
In [2]: from deal import pre, post, inv, Scheme
...: @post(lambda x: x > 0, debug=True)
...: def my_sum(*args):
...: return sum(args)
...:If you run python with -O option, contracts will be disabled. This is uses Python’s __debug__ option:
The built-in variable __debug__ is True under normal circumstances, False when optimization is requested (command line option -O). - Official documentation
Perfomance
NOTICE: 1 µs == 1000 ns
@pre and @post:
In [1]: f = lambda x: x
In [2]: pre_f = pre(lambda x: True)(f)
In [3]: post_f = post(lambda x: True)(f)
In [4]: %timeit f(10)
92.3 ns ± 3.62 ns per loop (mean ± std. dev. of 7 runs, 10000000 loops each)
In [5]: %timeit pre_f(10)
2.07 µs ± 92.5 ns per loop (mean ± std. dev. of 7 runs, 100000 loops each)
In [6]: %timeit post_f(10)
2.03 µs ± 18.6 ns per loop (mean ± std. dev. of 7 runs, 100000 loops each)+1 µs
@inv:
In [1]: class A:
...: x = 4
...:
In [2]: InvA = inv(lambda obj: True)(A)
In [3]: a = A()
In [4]: inv_a = InvA()
In [5]: %timeit a.x = 10
76.4 ns ± 1.36 ns per loop (mean ± std. dev. of 7 runs, 10000000 loops each)
In [6]: %timeit inv_a.x = 10
6.89 µs ± 408 ns per loop (mean ± std. dev. of 7 runs, 100000 loops each)+6 µs
Changelog
1.0. @pre, @post, @inv, error messages customization.
1.1. @inv chaining.
1.2. Travis CI, wrapper updating.
2.0. Schemes, djburger validators support.
2.1 @pre and @post can decorate class methods.
2.2 new debug option for optional disabling contracts on production.
Contributors
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
File details
Details for the file deal-2.2.1.tar.gz.
File metadata
- Download URL: deal-2.2.1.tar.gz
- Upload date:
- Size: 11.2 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/1.11.0 pkginfo/1.4.2 requests/2.19.1 setuptools/39.2.0 requests-toolbelt/0.8.0 tqdm/4.23.4 CPython/3.5.2
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 7ccdb2024c1b24f3e8c362d082b0a771f559f70562ac5f97c22711fadcd3d02c |
|
| MD5 | 8cac32530a0d71af78f293dc5298c985 |
|
| BLAKE2b-256 | 1d3d7d32d8dc2e490a0ef56d6e68373a7836ab0d7ef0a037a9484a786968ac7c |
