icontract

What it is and what it does

icontract is a Python library that implements design-by-contract through decorators, allowing you to declare preconditions (what must be true before a function runs), postconditions (what must be true after), and invariants (what must always be true for a class). When a contract is violated, it raises a ViolationError with a detailed message that includes the contract condition itself, the values of all relevant variables at the time of violation, and any custom description you provided.

The library is built on three runtime dependencies: asttokens, contextvars, and typing_extensions. It supports Python 3.6 through 3.13 and has been in production use since 2018. Unlike simpler assertion-based approaches, icontract automatically extracts and displays variable values without requiring you to write custom error messages, following the DRY principle. It also supports contract inheritance, allowing subclasses to weaken preconditions and strengthen postconditions.

Use it for:

• Add runtime validation to library APIs to catch misuse early with informative error messages
• Document and enforce class invariants in complex stateful objects to prevent invalid states
• Verify function inputs and outputs in data processing pipelines to catch logic errors
• Generate automated test cases by inferring test strategies from contracts
• Enforce contracts on HTTP APIs to validate request and response contracts

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

icontract enforces design-by-contract in Python through decorators that validate preconditions, postconditions, and class invariants, with detailed violation messages showing source code and variable values.

Yes, if you want runtime contract enforcement with detailed diagnostics. The permissive MIT license, low install friction, and lack of known vulnerabilities make it safe to adopt. Aging maintenance (197 days since last release) is a minor concern but not a blocker—the library is stable and the repository remains active. Best suited for teams that value explicit contract documentation and detailed failure messages over minimal runtime overhead.

Install

icontract on PyPI

pip install icontract

uv add icontract

poetry add icontract

Installing icontract

Before you install

Low friction install with three lightweight runtime dependencies (asttokens, contextvars, typing_extensions). Maintenance status is aging—last release was 197 days ago—but the repository remains active and unarchived with 411 stars.

License in practice

MIT license (permissive) places no restrictions on use, modification, or distribution in proprietary or open-source projects.

Quickstart

pip install icontract

import icontract

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

some_func(x=5)  # succeeds
some_func(x=1)  # raises ViolationError with details

Verify before relying

• Performance overhead of contract checking at runtime compared to assertion-based alternatives
• Compatibility with async/await patterns and coroutines
• Whether inheritance contract weakening/strengthening works correctly with multiple inheritance

Package facts

Evidence: icontract-2.7.3-py3-none-any.whl

Keywords: design-by-contract, precondition, postcondition, validation

Tags

More Quality Assurance packages