Stipulate

Contracts for Python interfaces.

Define. Validate. Evolve.

Stipulate checks dynamically supplied implementations against Python structural interfaces, explains mismatches, and preserves what available metadata cannot establish.

Status

This repository contains the Stipulate 0.1 implementation, design specification, and design probes. The core API checks declared Protocol compatibility without executing candidate operations. Earlier prototypes are historical inputs, not release evidence.

Install with python -m pip install . (CPython 3.11–3.14). See the implemented feature guide for the supported boundary. Independent Sol review is still required before release approval.

Define and validate

from typing import Protocol
from stipulate import Contract


class Storage(Protocol):
    def read(self, key: str) -> bytes | None: ...

    async def write(self, key: str, value: bytes) -> None: ...


class MemoryStorage:
    def __init__(self) -> None:
        self._items: dict[str, bytes] = {}

    def read(self, key: str) -> bytes | None:
        return self._items.get(key)

    async def write(self, key: str, value: bytes) -> None:
        self._items[key] = value


candidate = MemoryStorage()
storage_contract = Contract(Storage)
storage = storage_contract.validate(candidate)

Implementations are ordinary Python classes. They need no inheritance, registration, or decorators. Validation returns the original object, typed as Storage, after checking its available declarations against the contract. The constructor uses TypeForm for inference; the typing guide records supported checker settings, including the current mypy feature flag.

Strict validation is the default: incompatible or insufficient evidence raises ContractError. To allow missing implementation type annotations deliberately, use strict=False; known mismatches and unsupported or uninspectable candidate capabilities still fail. Invalid requirements fail contract construction.

Understand a result

result = storage_contract.check(candidate)
print(result)

if result:
    print("Storage declarations are compatible")

result.status
result.complete
result.errors()
result.unknowns()
result.evidence

check() reports candidate mismatches without raising ContractError. Truthiness means compatibility was established for every requirement; unknown evidence is false. Invalid contract definitions raise ContractDefinitionError. The result includes locations, reasons, and suggested fixes.

Stipulate compares signatures, annotation assignability, binding, and supported member capabilities. It assumes implementations honor their declarations; it does not execute methods to verify their behavior, validate future return values, or prevent later mutation. Annotation resolution may execute Python annotation expressions in the default trusted mode.

Friendly errors

Incompatible with Storage
2 incompatible findings; 0 unknown findings (0 blocked obligations).

read.key
  The implementation input is too narrow for required caller values
  Required: str
  Provided: bytes
  [parameter_type; incompatible]

write.kind
  The coroutine execution kind differs
  [async_mismatch; incompatible]

Interface shorthand — experimental design target

from stipulate import Interface

class Storage(Interface):
    def read(self, key: str) -> bytes | None: ...

storage = Storage.validate(candidate)

This shorthand is not a 0.1 promise. It must preserve structural typing, precise class-side methods, inheritance, and clean protocol members in installed-package Pyright/mypy tests before promotion. The supported 0.1 plan uses Protocol plus Contract, with the same method-based operations and compatibility engine.

Evolution and tooling — later releases

report = Contract(StorageV1).compare(Contract(StorageV2))
schema = storage_contract.schema()
fingerprint = storage_contract.fingerprint()

Comparison will report implementer and consumer compatibility separately. Unknown results cannot certify a non-breaking change. Schemas and fingerprints will be versioned before publication. None of these three operations is in the 0.1 public surface.

Documentation

Start with the quickstart. The experience design specifies the API journey, readable reports, and usability bar.

• Product Vision
• Public Interface Model
• Contract Engine
• Architecture
• Type System
• Validation Engine
• Static Typing
• Errors
• Performance and Caching
• Testing
• Compatibility
• Dependencies
• Competition
• Pydantic Integration
• Roadmap and 0.x release phases
• Release and PyPI trusted publishing
• Design Decisions
• Implementation Plan
• Phase 0.1 implementation contract
• Open Technical Problems
• Design probes

The roadmap owns release scope; design decisions own durable policy; focused specifications own behavior; the open-problem register owns implementation evidence and unresolved acceptance work. Contradictions must be reconciled in the same change. A decision does not count as a tested implementation.