Verdict — Python

The Python implementation of Verdict — a small, zero-dependency, async-native rule-evaluation engine. See the top-level README.md for what Verdict is and why it's shaped this way in narrative form; this doc is just "how do I install it and write my first rule" for Python specifically.

This exact file is also what PyPI renders as the package description — none of its sibling files travel with a pip install, which is why every link below is an absolute GitHub URL rather than a relative path; on GitHub itself they work exactly the same way.

Install

pip install verdict-rules

The distribution on PyPI is named verdict-rules (the name verdict was already taken by an unrelated package), but the import name is plain verdict:

from verdict import Rule, FunctionRule, AndRule, OrRule, RulesEngine

A first rule

A FunctionRule's predicate returns a full RuleResult, not a bare boolean — that keeps it in control of detail/data, not just pass/fail:

import asyncio
from verdict import FunctionRule, AndRule, RuleResult, RulesEngine

async def under_limit(context: dict) -> RuleResult:
    return RuleResult(
        rule_name="under_limit",
        passed=context["requests_this_minute"] < context["limit"],
    )

async def in_good_standing(context: dict) -> RuleResult:
    return RuleResult(
        rule_name="in_good_standing",
        passed=context["account_status"] == "active",
    )

async def main() -> None:
    can_proceed = AndRule(
        "can_proceed",
        [
            FunctionRule("under_limit", under_limit),
            FunctionRule("in_good_standing", in_good_standing),
        ],
    )
    engine = RulesEngine([can_proceed])
    result = await engine.run_named(
        "can_proceed",
        {"requests_this_minute": 3, "limit": 10, "account_status": "active"},
    )
    print(result.passed)  # True

asyncio.run(main())

What it guarantees

• Sequential evaluation, never concurrent. Composites use a plain for loop with await, never asyncio.gather. Short-circuiting only means something if later work never starts — and because the returned boolean is identical either way, getting this wrong is silent.
• Vacuous truth has a polarity. AndRule([]) passes, OrRule([]) fails. Deliberately asymmetric.
• Emptiness is not absence. An empty composite folds to its identity; an unknown rule name or group raises KeyError. A group exists only because some rule declared it, so a lookup matching nothing can only be a mistake — and a misspelled group silently approving is the worst failure an eligibility check can have. Use rule_names / group_names to check rather than catch.
• RuleResult.data is opaque — only what actually ran, never padded, never flattened.
• Zero runtime dependencies.

Where to go next

Development

uv sync
uv run pytest