**User documentation**

**Developer documentation**

# 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**