icontract

icontract provides design-by-contract to Python3 with informative violation messages and inheritance.

It also gives a base for a flourishing of a wider ecosystem:

A linter pyicontract-lint,
A sphinx plug-in sphinx-icontract,
A tool icontract-hypothesis for automated testing and ghostwriting test files which infers Hypothesis strategies based on the contracts,
- together with IDE integrations such as icontract-hypothesis-vim, icontract-hypothesis-pycharm, and icontract-hypothesis-vscode,
Directly integrated into CrossHair, a tool for automatic verification of Python programs,
- together with IDE integrations such as crosshair-pycharm and crosshair-vscode, and
An integration with FastAPI through fastapi-icontract to enforce contracts on your HTTP API and display them in OpenAPI 3 schema and Swagger UI, and
An extensive corpus, Python-by-contract corpus, of Python programs annotated with contracts for educational, testing and research purposes.

Teasers

We give a couple of teasers here to motivate the library. Please see the documentation available on icontract.readthedocs.io for a full scope of its capabilities.

The script is also available as a repl.it post.

>>> import icontract

>>> @icontract.require(lambda x: x > 3)
... def some_func(x: int, y: int = 5) -> None:
...     pass
...

>>> some_func(x=5)

# Pre-condition violation
>>> some_func(x=1)
Traceback (most recent call last):
  ...
icontract.errors.ViolationError: File <doctest README.rst[1]>, line 1 in <module>:
x > 3:
x was 1
y was 5

# Pre-condition violation with a description
>>> @icontract.require(lambda x: x > 3, "x must not be small")
... def some_func(x: int, y: int = 5) -> None:
...     pass
...
>>> some_func(x=1)
Traceback (most recent call last):
  ...
icontract.errors.ViolationError: File <doctest README.rst[4]>, line 1 in <module>:
x must not be small: x > 3:
x was 1
y was 5

# Pre-condition violation with more complex values
>>> class B:
...     def __init__(self) -> None:
...         self.x = 7
...
...     def y(self) -> int:
...         return 2
...
...     def __repr__(self) -> str:
...         return "instance of B"
...
>>> class A:
...     def __init__(self) -> None:
...         self.b = B()
...
...     def __repr__(self) -> str:
...         return "instance of A"
...
>>> SOME_GLOBAL_VAR = 13
>>> @icontract.require(lambda a: a.b.x + a.b.y() > SOME_GLOBAL_VAR)
... def some_func(a: A) -> None:
...     pass
...
>>> an_a = A()
>>> some_func(an_a)
Traceback (most recent call last):
  ...
icontract.errors.ViolationError: File <doctest README.rst[9]>, line 1 in <module>:
a.b.x + a.b.y() > SOME_GLOBAL_VAR:
SOME_GLOBAL_VAR was 13
a was instance of A
a.b was instance of B
a.b.x was 7
a.b.y() was 2

# Post-condition
>>> @icontract.ensure(lambda result, x: result > x)
... def some_func(x: int, y: int = 5) -> int:
...     return x - y
...
>>> some_func(x=10)
Traceback (most recent call last):
  ...
icontract.errors.ViolationError: File <doctest README.rst[12]>, line 1 in <module>:
result > x:
result was 5
x was 10
y was 5


# Pre-conditions fail before post-conditions.
>>> @icontract.ensure(lambda result, x: result > x)
... @icontract.require(lambda x: x > 3, "x must not be small")
... def some_func(x: int, y: int = 5) -> int:
...    return x - y
...
>>> some_func(x=3)
Traceback (most recent call last):
  ...
icontract.errors.ViolationError: File <doctest README.rst[14]>, line 2 in <module>:
x must not be small: x > 3:
x was 3
y was 5

# Invariant
>>> @icontract.invariant(lambda self: self.x > 0)
... class SomeClass:
...     def __init__(self) -> None:
...         self.x = -1
...
...     def __repr__(self) -> str:
...         return "an instance of SomeClass"
...
>>> some_instance = SomeClass()
Traceback (most recent call last):
 ...
icontract.errors.ViolationError: File <doctest README.rst[16]>, line 1 in <module>:
self.x > 0:
self was an instance of SomeClass
self.x was -1

Installation

Install icontract with pip:

pip3 install icontract

Versioning

We follow Semantic Versioning. The version X.Y.Z indicates:

X is the major version (backward-incompatible),
Y is the minor version (backward-compatible), and
Z is the patch version (backward-compatible bug fix).

Metadata

Release files for icontract 2.7.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for icontract 2.7.3
File	Size	Uploaded	Provenance
icontract-2.7.3.tar.gz	68.4 kB	Jan 29, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for icontract 2.7.3
File	Interpreter	ABI	Platform	Reset
icontract-2.7.3-py3-none-any.whl 41.0 kB Jan 29, 2026 Without provenance	Python 3	none	any	Details

Total release size: 109.3 kB

Release files / icontract-2.7.3.tar.gz

Download URL	icontract-2.7.3.tar.gz
Size	68.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`df37a43d86d532407bc6b84dea29dd9f7ece794b73211769fa8a33a76b8ed145`
BLAKE2b-256 checksum How to use checksums	`41938a7d5850d848cba73aa094b961459d8101b7c96837b2e8dc91083adcf7ae`
Upload date	Jan 29, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.14.2`

Release files / icontract-2.7.3-py3-none-any.whl

Download URL	icontract-2.7.3-py3-none-any.whl
Size	41.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`8fb0f93f71211416f214f37c01b8017fdc8c079d70159f49f0ddcc10918c14d0`
BLAKE2b-256 checksum How to use checksums	`eeaaffc16b7ed17e052e7d2140e66336f829e9383f61f31249c4d181e12fcdea`
Upload date	Jan 29, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.14.2`

Security for icontract 2.7.3

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.