API

require

class icontract.require

Decorate a function with a precondition.

The arguments of the precondition are expected to be a subset of the arguments of the wrapped function.

__init__(condition: ~typing.Callable[[...], ~typing.Any], description: ~typing.Optional[str] = None, a_repr: ~reprlib.Repr = <reprlib.Repr object>, enabled: bool = True, error: ~typing.Optional[~typing.Union[~typing.Callable[[...], ~icontract._globals.ExceptionT], ~typing.Type[~icontract._globals.ExceptionT], BaseException]] = None) → None

Initialize.

Parameters:

• condition –

  precondition predicate

  If the condition returns a coroutine, you must specify the error as coroutines have side effects and can not be recomputed.

• description – textual description of the precondition

• a_repr – representation instance that defines how the values are represented

• enabled –

  The decorator is applied only if this argument is set.

  Otherwise, the condition check is disabled and there is no run-time overhead.

  The default is to always check the condition unless the interpreter runs in optimized mode (-O or -OO).

• error –

  The error is expected to denote either:

  • A callable. error is expected to accept a subset of function arguments and return an exception. The error is called on contract violation and the resulting exception is raised.

  • A subclass of BaseException which is instantiated with the violation message and raised on contract violation.

  • An instance of BaseException that will be raised with the traceback on contract violation.

__call__(func: CallableT) → CallableT

Add the precondition to the list of preconditions of the function func.

The function func is decorated with a contract checker if there is no contract checker in the decorator stack.

Parameters:

func – function to be wrapped

Returns:

contract checker around func if no contract checker on the decorator stack, or func otherwise

snapshot

class icontract.snapshot

Decorate a function with a snapshot of argument values captured prior to the function invocation.

A snapshot is defined by a capture function (usually a lambda) that accepts one or more arguments of the function. If the name of the snapshot is not given, the capture function must have a single argument and the name is equal to the name of that single argument.

The captured values are supplied to postconditions with the OLD argument of the condition and error function. Snapshots are inherited from the base classes and must not have conflicting names in the class hierarchy.

__init__(capture: Callable[[...], Any], name: Optional[str] = None, enabled: bool = True) → None

Initialize.

Parameters:

• capture – function to capture the snapshot accepting a one or more arguments of the original function prior to the execution

• name – name of the snapshot; if omitted, the name corresponds to the name of the input argument

• enabled –

  The decorator is applied only if enabled is set.

  Otherwise, the snapshot is disabled and there is no run-time overhead.

  The default is to always capture the snapshot unless the interpreter runs in optimized mode (-O or -OO).

__call__(func: CallableT) → CallableT

Add the snapshot to the list of snapshots of the function func.

The function func is expected to be decorated with at least one postcondition before the snapshot.

Parameters:

func – function whose arguments we need to snapshot

Returns:

func as given in the input

ensure

class icontract.ensure

Decorate a function with a postcondition.

The arguments of the postcondition are expected to be a subset of the arguments of the wrapped function. Additionally, the argument “result” is reserved for the result of the wrapped function. The wrapped function must not have “result” among its arguments.

__init__(condition: ~typing.Callable[[...], ~typing.Any], description: ~typing.Optional[str] = None, a_repr: ~reprlib.Repr = <reprlib.Repr object>, enabled: bool = True, error: ~typing.Optional[~typing.Union[~typing.Callable[[...], ~icontract._globals.ExceptionT], ~typing.Type[~icontract._globals.ExceptionT], BaseException]] = None) → None

Initialize.

Parameters:

• condition –

  postcondition predicate.

  If the condition returns a coroutine, you must specify the error as coroutines have side effects and can not be recomputed.

• description – textual description of the postcondition

• a_repr – representation instance that defines how the values are represented

• enabled –

  The decorator is applied only if this argument is set.

  Otherwise, the condition check is disabled and there is no run-time overhead.

  The default is to always check the condition unless the interpreter runs in optimized mode (-O or -OO).

• error –

  The error is expected to denote either:

  • A callable. error is expected to accept a subset of function arguments and return an exception. The error is called on contract violation and the resulting exception is raised.

  • A subclass of BaseException which is instantiated with the violation message and raised on contract violation.

  • An instance of BaseException that will be raised with the traceback on contract violation.

__call__(func: CallableT) → CallableT

Add the postcondition to the list of postconditions of the function func.

The function func is decorated with a contract checker if there is no contract checker in the decorator stack.

Parameters:

func – function to be wrapped

Returns:

contract checker around func if no contract checker on the decorator stack, or func otherwise

invariant

class icontract.invariant

Represent a class decorator to establish the invariant on all the public methods.

Class method as well as “private” (prefix __) and “protected” methods (prefix _) may violate the invariant. Note that all magic methods (prefix __ and suffix __) are considered public and hence also need to establish the invariant. To avoid endless loops when generating the error message on an invariant breach, the method __repr__ is deliberately exempt from observing the invariant.

The invariant is checked before and after the method invocation.

As invariants need to wrap dunder methods, including __init__, their conditions can not be async, as most dunder methods need to be synchronous methods, and wrapping them with async code would break that constraint.

For efficiency reasons, we do not check the invariants at the calls to __setattr__ and __getattr__ methods by default. If you indeed want to check the invariants in those calls as well, make sure to adapt the argument check_on accordingly.

__init__(condition: ~typing.Callable[[...], ~typing.Any], description: ~typing.Optional[str] = None, a_repr: ~reprlib.Repr = <reprlib.Repr object>, enabled: bool = True, error: ~typing.Optional[~typing.Union[~typing.Callable[[...], ~icontract._globals.ExceptionT], ~typing.Type[~icontract._globals.ExceptionT], BaseException]] = None, check_on: ~icontract._types.InvariantCheckEvent = InvariantCheckEvent.CALL) → None

Initialize a class decorator to establish the invariant on all the public methods.

Parameters:

• condition –

  invariant predicate.

  The condition must not be a coroutine function as dunder functions (including __init__) of a class can not be async.

• description – textual description of the invariant

• a_repr – representation instance that defines how the values are represented

• enabled –

  The decorator is applied only if this argument is set.

  Otherwise, the condition check is disabled and there is no run-time overhead.

  The default is to always check the condition unless the interpreter runs in optimized mode (-O or -OO).

• error –

  The error is expected to denote either:

  • A callable. error is expected to accept a subset of function arguments and return an exception. The error is called on contract violation and the resulting exception is raised.

  • A subclass of BaseException which is instantiated with the violation message and raised on contract violation.

  • An instance of BaseException that will be raised with the traceback on contract violation.

• check_on –

  Specify when to check the invariant.

  • If InvariantCheckEvent.CALL is set, the invariant will be checked on all the method calls except __setattr__.

  • If InvariantCheckEvent.SETATTR is set, the invariant will be checked on __setattr__ calls.

Returns:

__call__(cls: ClassT) → ClassT

Decorate each of the public methods with the invariant.

Go through the decorator stack of each function and search for a contract checker. If there is one, add the invariant to the checker’s invariants. If there is no checker in the stack, wrap the function with a contract checker.

DBCMeta

class icontract.DBCMeta(name, bases, namespace, **kwargs)

Define a meta class that allows inheritance of the contracts.

The preconditions are weakened (“require else”), while postconditions (“ensure then”) and invariants are strengthened according to the inheritance rules of the design-by-contract.

DBC

class icontract.DBC

Provide a standard way to create a class which can inherit the contracts.

ViolationError

class icontract.ViolationError

Indicate a violation of a contract.

InvariantCheckEvent

class icontract.InvariantCheckEvent(value)

Define when an invariant should be checked.

Attributes:

CALL	Evaluate the invariant before and after all calls to a method.
SETATTR	Evaluate the invariant before and after all the calls to __setattr__.
ALL	Always evaluate the invariant, *i.e., both on calls and on attributes set.

CALL = 1

Evaluate the invariant before and after all calls to a method.

SETATTR = 2

Evaluate the invariant before and after all the calls to __setattr__.

ALL = 3

Always evaluate the invariant, *i.e., both on calls and on attributes set.