postulate

Make the assumptions your code rests on explicit, loud, and inspectable.

Every nontrivial system runs on assumptions nobody wrote down: "this queue never has duplicates," "the upstream client retries on 5xx," "this list is never empty." They live in comments, if anywhere — and comments don't fail loudly when they stop being true, and nobody can list all of them when something breaks at 3am.

postulate is a ~150-line, zero-dependency library that turns those assumptions into first-class, checkable, reportable facts about your system.

Install

pip install postulate

Usage

Check an assumption at runtime

import postulate

def process_batch(batch):
    postulate.assume(len(batch) > 0, "batch is never empty", batch_id=batch.id)
    ...

Unlike a bare assert, this:

• is never stripped by python -O
• is recorded in the registry whether it passes or fails
• raises AssumptionViolated with the assumption's own words plus whatever context you passed, so a postmortem doesn't have to reverse-engineer what the code was hoping was true

Declare an assumption you aren't checking

Some assumptions are too expensive, impossible, or out of scope to check at runtime — but they're still load-bearing, and still worth writing down where they'll be found:

@postulate.holds("upstream producer never sends duplicate event ids")
def handle_event(event):
    ...

holds doesn't change behavior at all. It just attaches the assumption to the function and adds it to the registry.

Get the manifest

print(postulate.report())

# Assumptions

## Checked at runtime
- **batch is never empty** — never violated (worker.py:12 in process_batch)

## Declared, not runtime-checked
- **upstream producer never sends duplicate event ids** — (worker.py:30 in handle_event)

Pass fmt="json" for machine-readable output.

Scan a codebase without running it

Assumptions on code paths that have never executed are invisible to the runtime registry. The static scanner finds them anyway, straight from the AST:

postulate scan src/

Why this exists

This library follows one rule: a rule (or assumption) that nobody can explain is a rule that will misfire in production. postulate doesn't prevent bugs. It makes sure that when one of your assumptions turns out to be wrong, you find out from a loud, specific exception — not from a customer, three services downstream, a week later.

Development

pip install -e ".[dev]"
pytest

License

MIT