Handy decorator to define contracts with dependency injection in Python 3.10 and above
design-by-contractA minimalistic decorator for the design by contract pattern written in a just little more than 100 lines of modern Python 3.10 code (not counting documentation and logging).
Contracts are useful to impose restrictions and constraints on function arguments in a way that
Install with
pip install design-by-contract
Warning
This project started as a weekend project to learn recent additions to the language (typing.Annotated and typing.ParamSpec, the walrus operator, pattern matching and others). This means also that this package and its documentation should be considered as work in progress.
You probably shouldn't use it in production yet! But if you do, let me know how it went. Please leave a star if you like this project!
The decorator has been mainly designed with numpy arrays and pandas DataFrames in mind but can be universally applied. Contracts are defined as lambda functions that are attached to the function arguments via the new Annotated type that allows adding additional information to the arguments' and return value's type hint. Arguments are inserted into the lambda via dependency injection and working with symbols to increase readability is supported.
Let's look at an example for for matrix multiplication!
from typing import Annotated
import numpy as np
from design_by_contract import contract
@contract
def spam(
first: Annotated[np.ndarray, lambda first, m, n: (m, n) == first.shape], # symbols m and n represent the shape of `a`
second: Annotated[np.ndarray, lambda second, n, o: (n, o) == second.shape], # `b` number of columns matches the number of rows of `a`
) -> Annotated[np.ndarray, lambda x, m, o: x.shape == (m, o)]: # `x` holds the return value. The shape of `x` must equal `x` times `o`
"""Matrix multiplication"""
return a @ b
Contracts are lambdas with one argument named like the annotated argument. Alternatively, x can be used as a shortcut which means
that you cannot use x as a function argument unless you choose another reserved (using the reserved argument contractor decorator).
@contract(reserved='y')
def spam(
first: Annotated[np.ndarray, lambda y, m, n: (m, n) == y.shape],
second: Annotated[np.ndarray, lambda y, n, o: (n, o) == y.shape],
) -> Annotated[np.ndarray, lambda y, m, o: y.shape == (m, o)]:
"""Matrix multiplication"""
return a @ b
Symbolic calculus is supported to certain degree to make your life easier. The symbols m, n and o are defined in a way
that
$$ \text spam: R^{m \times x} \times R^{n\times o} \rightarrow R^{m\times o} $$
Note however, that this package does not intend to be a symbolic calculus package and therefore, there are some strong limitations.
Python does not allow for assignments (=) in a lambda expression and therefore,
the equality operator (==) is chosen to act a replacement. Unknown arguments are replaced under the hood by an instance of UnresolvedSymbol
that overload this operator. As a consequence, each symbol, therefore has to be first appear in an equality before it can be used in a different lambda expression!
The following example will raise an error for instance:
@contract
def spam(
a: Annotated[np.ndarray, lambda x, m, n: (m, n) == x.shape and m > 2], # you cannot "assign" and use `m` in the same lambda
# Annotated[np.ndarray, lambda x, m, n: (m, n) == x.shape, lambda x, m: m > 2] # this would work
b: Annotated[np.ndarray, lambda x, n, o: (n, o) == x.shape],
) -> Annotated[np.ndarray, lambda x, m, o: x.shape == (m, o)]:
return a @ b
spam(a, b) # raises: '>' not supported between instances of 'UnresolvedSymbol' and 'int'
This design decision is arguably unclean but allows for elegant contract expressions and a very clean and compact implementation. Different approaches involving symbolic algebra packages like sympy or parsing a syntax trees were considered but turned out to be too complex to implement. The next best alternative is using a domain-specific language (DLS) as done in the excellent pycontracts package, which actually inspired this project. By using python, calculus in the contract can be arbitrarily complex without the need for extending the DSL (i.e., including python functions):
@contract
def spam(
a: Annotated[np.ndarray, lambda x, m, o: (m, o) == x.shape],
b: Annotated[np.ndarray, lambda x, n, o: (n, o) == x.shape],
) -> Annotated[np.ndarray, lambda x, m,n,o: x.shape == (m+n, o)]:
print(np.vstack((a,b)).shape)
return np.vstack((a,b))
spam(np.zeros((3, 2)), np.zeros(( 4, 2)))
The decorator is also quite handy for being used with pandas data frames:
@contract
def spam(a: Annotated[pd.DataFrame,
lambda x, c: c == {'C','B'}, # `x` or the argument name must be passed to the lambda
lambda x, c: c.issubset(x.columns) # Remember, we need to use two lambdas here!
],
b: Annotated[pd.DataFrame,
lambda x, c: c <= set(x.columns) # equivalent to `issubset` but more elegant
]
) -> Annotated[pd.DataFrame,
lambda x, c: c <= set(x.columns)]:
"""Matrix multiplication"""
return pd.merge(a,b,on=['B','C'])
spam(a, b)
Note that evaluation is not optimized. In production, you might consider disabling evaluation by passing
evaluate=False as a parameter to the contract decorator.
decorator).
Plays well with SphinxI had the idea a while ago when reading about typing.Annotated in the release notes of Python 3.9.
Eventually, it turned out to be a nice, small Weekend project and a welcomed
opportunity to experiment with novel features in Python 3.10.
In addition, it has been a good exercise to practice several aspects of modern and clean Python development and eventually
might serve as an example for new Python developers:
If you think it's cool, please leave a star. And who knows, it might actually be useful.
It appears that the related (still active) projects have significantly larger code bases (include parsers for a domain-specific language, automated testing, etc.) but also try to achieve additional and wider goals (automated testing, pure functions, etc.). The main strength of this project, in my opinion, lies in its compact codebase and intuitiveness of the dependency injection.
PyContracts. Originally inspired this project. Although it requires a domain specific language, it supports implicitly defining variables for array shapes (see below). This package tries to achieve a similar goal in pure Python but it requires a formal definition of variables.
@contract
@contract(a='list[ M ](type(x))',
b='list[ N ](type(x))',
returns='list[M+N](type(x))')
def my_cat_equal(a, b):
''' Concatenate two lists together. '''
return a + b
icontract and deal:
Rely on conditions defined as lambdas much like this Project. They don't use the Annotated syntax
and their codebases are significantly larger.
Pull requests are welcome!
decorator, add fully typed replacementMIT License, Copyright 2022 Stefan Ulbrich
FAQs
Handy decorator to define contracts with dependency injection in Python 3.10 and above
We found that design-by-contract demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
The Linux Foundation is warning open source developers that compliance with global sanctions is mandatory, highlighting legal risks and restrictions on contributions.
Security News
Maven Central now validates Sigstore signatures, making it easier for developers to verify the provenance of Java packages.
Security News
CISOs are racing to adopt AI for cybersecurity, but hurdles in budgets and governance may leave some falling behind in the fight against cyber threats.