Language reference

This section describes PyContracts’ language for specifying contracts.

Simple types

The simplest kind of contract consists in declaring the type of a value. These are the supported primitive types:

dict, list, tuple, float, int, number, array, bool, None

Moreover, there are two kinds of wild-cards:

Matches any object.
Never matches anything — useful for debugging.


PyContracts allows to use variables to bind to sub-expressions and reuse later (it is simpler than it sounds).

There are two kinds of variables. The first kind is denoted by an uppercase letter, and it is constrained to bind to integer values.


Lower-case letters denote general-purpose variables that can bind to any type:

a b c d e f g h i j k l m n o p q r s t u w v x y z


The reason for having specialized variables for integers is to encourage a writing style in which uppercase letters denote lengths, shapes, etc. Moreover, an error will be thrown if they do not bind to integers, which helps in catching mistakes.

Scoped variables

Contracts can refer to external variables using $PythonVariable. For example, a typical application is the following:

from module import MyClass

def f(x):

Logical expressions

Two logical operators are supported:


Expressed with a comma (,).

For example, the expression

check("contract1,contract2", value)

is roughly equivalent to

check("contract1", value) and check("contract2", value)

except that variables in the contracts are evaluated in the same context.


Expressed with a pipe symbol (|).

The semantic is that the first matching expression is chosen.

The expression:

check("contract1|contract2", value)

is roughly equivalent to:

if value respects "contract1":
   return True
elif value respects "contract2":
   return True
   return False

The AND has precedence over OR. For example, the expression


is evaluated the same as

(a, b) | c
Examples of contracts with logical operators
Contract expression Meaning
None|int Either None or an integer.


This section must still be written.

Arithmetic and comparison

This section must still be written.

Details of variable binding

This section must still be written.


You can specify that the value must be a list, and specify optional constraints for its length and for its elements.

The general syntax is:

Examples of list contracts
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.
tuple(list[N], list[N]) A tuple of two lists of the same length.


The contract seq has the same syntax as list but matches any sequence.



You can either specify a length (with square brackets), or specify a contract for each element:



tuple(element1, ..., elementN)

In the latter case, you are also specifying implicitly the number of elements.


The syntax for tuples is somewhat a special case. While list(int,>0) signifies a list of positive integers (or empty list), tuple(int, >0) means a tuple with exactly 2 elements, the first of which should be an integer, and the second must be positive (but not necessarily integer.)

Examples of tuple contracts
Contract expression Meaning
tuple A tuple.
tuple[2] A tuple with two elements.
tuple(*,*) A tuple with two elements.
tuple(int) A tuple with one integer element.
tuple(int, int) A tuple with two integer elements.
tuple[>=2] A tuple with at least two elements.


For dictionary, you can specify a length contract, as well as a contract for its keys and values:



dict(key_contract: value_contract)

dict[length_contract](key_contract: value_contract)
Examples of dict contracts
Contract expression Meaning
dict Any dictionary.
dict[2] A dictionary with two elements.
dict(*: *) Any dictionary.
dict(*: int) A dictionary whose values are integers.
dict(str: *) A dictionary whose keys are strings
dict(str: tuple(type(x),type(y)) ), x!=y A dictionary whose keys are strings, and whose values are tuples with two elements, of two different types x and y.


The contract map has the same syntax as dict but matches any mapping.



map(key_contract: value_contract)

map[length_contract](key_contract: value_contract)

Numpy arrays

The support for Numpy arrays was one of the motivations for me to develop PyContracts. Numpy is one of the best and most useful Python packages around. It supports the ndarray datatype which allows for operations with tensors of arbitrary dimensions.

All of that is very powerful, but it might be a bit confusing, especially because Numpy tends to be very liberal when it gets to operations between arrays. For example, the operation A * B, if A is a 2D matrix, is well defined when B is a scalar, a vector, or a matrix. Sometimes you want to be certain of your assumptions, otherwise you risk of ignoring powerful bugs.


Researchers tend to be a bit paranoid, because often you don’t know what to expect out of your algorithms. A stupid bug can lead to an exciting (false) discovery!

So PyContracts offers several shortcuts for Numpy arrays, and the error messages tend to be more descriptive.

The general syntax looks like this:





Shape contracts

A shape contract is specified using a special syntax of the kind:

dimension1 x dimension2 x dimension3

dimension1 x dimension2 x dimension3 x …

The ellipsis is part of the syntax and specifies that more dimensions are allowed.

Each dimension can be specified as a number, with variables, or as a contract.

Examples of array shape contracts
Contract expression Meaning
array Any array.
array[3] A 1D array with 3 elements (shape=(3,)).
array[3x2] A 2D array with 3 rows and 2 columns (shape=(3,2)).
array[3 x ...] A nD array with 3 rows and arbitrary other dimensions.
array[3xN], N>=2 A 2D array with 3 rows and at least 2 columns.
array[NxN], N>0 A square matrix.
array[NxNx...], N>0 A tensor with the first two dimensions of equal size.
list(array[NxN]), N>0 A list of square matrices of the same size.

Numpy-specific contracts

A numpy contract is special and implemented separately from the other PyContracts contract. Right now, we support:

Datatype contracts

These specify the datatype of the array. Available:

uint8 uint16 uint32 uint64 int8 int16 int32  int64 float32 float64
Arithmetic comparisons

These have the semantics that all elements must satisfy the contract. They appear similar to the normal PyContracts comparison:

>0   <0   <=1   =0
Examples of array elements contracts
Contract expression Meaning
array Any array.
array(>=0) An array with nonnegative elements.
array(int8,>=0) An array with nonnegative integer elements.
array[NxN](float,>=0,<=1) A square matrix with float elements in the interval [0,1].
array[NxN](int,(0|1)) A square matrix with each element equal either to 0 or 1 (this could model a directed graph).

Other examples

Here is an example that first uses new_contract() to specify a domain-specific array type (rgb, rgba), then uses PyContracts to be sure that the two given images and the result values have coherent dimensions. Notice how the contracts serve very well as documentation.

from contracts import contract, new_contract

new_contract('rgb',  'array[HxWx3](uint8),H>0,W>0')
new_contract('rgba', 'array[HxWx4](uint8),H>0,W>0')

def blend_images(image1, image2):
         Blends two images together.

         :param image1: The first image to blend.
         :type image1: rgb,array[HxWx*]

         :param image2: The second image to blend. Can have an alpha layer.
         :type image2: (rgb|rgba),array[HxWx*]

         :return: The blended image.
         :rtype: rgb,array[HxWx3]

If you want to have a function that accepts a list of images, you would write:

def blend_images(images):
         Blends a series of images together.

         :type images: list[N](rgb,array[HxWx*]), N>=2

         :rtype: rgb,array[HxWx3]

Advanced topic: the context isolate operator

PyContracts has a special construct $(...) used to separate the context of variables. The semantics is that the variables assigned inside $(...) are not propagated outside.

Examples of $() contracts
Contract expression Meaning
list(tuple(type(x),type(y)),x!=y) A list whose elements are tuples with two elements, of two different types x and y (x and y are common among the list elements ).
list( $( tuple(type(x),type(y)),x!=y) ) A list whose elements are tuples with two elements, of two different types x and y. (x and y are not joined among the list elements ).