Quick tour¶

The contracts are specified using the type clause of RST-style docstrings (now accepted as standard in the python libraries); or, they can be passed explicitly to the @contract decorator. In this example, PyContracts is smart enough to check that the two parameters a and b are matrices of compatible dimensions. Then, it checks that the result value is of compatible dimensions as well.

import numpy
from contracts import contract

@contract
def matrix_multiply(a,  b):
    ''' Multiplies two matrices together.

        :param a: The first matrix. Must be a 2D array.
         :type a: array[MxN],M>0,N>0

        :param b: The second matrix. Must be of compatible dimensions.
         :type b: array[NxP],P>0

          :rtype: array[MxP]
    '''
    return numpy.dot(a, b)

PyContracts can come in handy when you have operations that could be one-liners if you are sure of the types of the parameters, but doing all the checking adds to the complexity of the code.

In the next example we check that:

The two lists have elements of the same type (indicated by the variable x);

The returned list has the correct size (the sum of the two lengths).

@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

The philosophy is to make the simple cases easy, and the difficult possible, while still retaining readability.

For example, we can either ask for a simple list, or specify more about it using the additional clauses.

Contract expression	Meaning
`list`	An instance of `list`.
`list[2]`	A list of two elements.
`list(int)`	A list of integers.
`list(number)`	A list of numbers.
`list[3](number)`	A list of exactly three numbers.
`list[>=3](number)`	A list of at least three numbers.
`list[>=3](number, >0)`	A list of at least three numbers, greater than 0.

PyContracts supports the use of variables. There are two kinds of variables: lower-case letters (a, b, …) are general-purpose variables, while upper-case letters (A, B, …) are constrained to bind to integer types; they are meant to represent sizes and shapes. Moreover, PyContracts can do arithmetic and comparisons.

Contract expression	Meaning
`tuple(list[N], list[N])`	A tuple with two lists of the same length.
`tuple(list[N], list[M]), N<M`	A tuple with two lists, the first one being shorter.
`list[>0](type(x))`	A non-empty list containing elements of all the same type.
`tuple(list(type(x)), list(type(x)))`	A tuple with two lists containing objects of the same type.

For the complete reference to the available contract expressions, see Language reference.

User documentation

Developer documentation