ensures

ensures is a simple Python package that implements the idea of Design by Contract described in the Pragmatic Paranoia chapter of The Pragmatic Programmer. That's the chapter where they say you should trust nobody, not even yourself.

Main Features

• Verification of lists of pre/post condition and invariant functions.
• Usage of arbitrary functions for such verification.
• Result-type return values.

Installation

pip install ensures

Usage

precondition / require

Runs a list of functions on all args.

Returns Error if any of them fails.

from ensures import precondition


def is_positive(x):
    """Check if a number is positive."""
    return x > 0


@precondition(is_positive)
def square_root(x):
    """Calculate square root with precondition that x must be positive."""
    return x**0.5

postcondition / ensure

Runs a list of functions on the result.

Returns Error if any of them fails.

from ensures import ensure


def result_is_even(result):
    """Check if result is even."""
    return result % 2 == 0


@ensure(result_is_even)  # Using the alias
def double_number(x):
    """Double a number with postcondition that result is even."""
    return x * 2

invariant

Runs a list of functions on all args.

Returns Error if any of them fails.

from ensures import invariant


@invariant(lambda x: x >= 0)  # Simple lambda invariant
def increment_counter(x):
    """Increment a counter with invariant that it stays non-negative."""
    return x + 1

Result Handling

Pattern matching is supported to unpack the Return value.

from ensures import Error, Success


result1 = square_root(1)
result2 = square_root(-1)  # This will return an Error instance

def handle_result(res):
    match res:
        case Success(value):
            print(f"Square root calculated: {value}")
        case Error(func, args):
            print(f"Precondition failed in {func.__name__} with args {args}")

handle_result(result1)
handle_result(result2)

More examples

Check examples.py

📊 Performance

Contract validation adds minimal overhead:

• Precondition: ~7x baseline function call
• Postcondition: ~8x baseline function call
• Memory: Constant memory usage, no leaks

See performance benchmarks for detailed analysis.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📝 Changelog

See CHANGELOG.md for a list of changes in each version.

📄 License

This project is licensed under the GPL-3.0-or-later License - see the LICENSE file for details.