Skip to main content

Documentation Test codecov

py-predicate

A typed Python library for composable predicates.

Predicates are first-class objects that can be combined with boolean operators, optimized algebraically, compiled to native callables for performance, serialized to multiple formats, and used to instrument functions with runtime contracts.

Full documentation: mrijk.github.io/py-predicate

Installation

pip install py-predicate

Quick start

from predicate import ge_p, le_p

ge_2 = ge_p(2)
le_5 = le_p(5)

between = ge_2 & le_5

between(3)  # True
between(7)  # False

filtered = [x for x in range(10) if between(x)]  # [2, 3, 4, 5]

Predicates compose with standard Python operators:

Operator Meaning
p & q both must hold (AndPredicate)
p | q either must hold (OrPredicate)
p ^ q exactly one must hold (XorPredicate)
~p negation (NotPredicate)

Built-in predicates

Comparisons: eq_p, ne_p, gt_p, ge_p, lt_p, le_p, is_close_p

Ranges: ge_le_p, ge_lt_p, gt_le_p, gt_lt_p (compiled to chained comparisons)

Type checks: is_int_p, is_str_p, is_float_p, is_bool_p, is_list_p, is_dict_p, is_none_p, is_not_none_p, is_instance_p, and many more

Collections: all_p, any_p, in_p, not_in_p, has_length_p, is_empty_p, is_not_empty_p, has_key_p, has_path_p

Typed collections: is_list_of_p, is_set_of_p, is_dict_of_p, is_tuple_of_p

Strings: regex_p, starts_with_p, ends_with_p, is_alpha_p, is_digit_p, is_upper_p, is_lower_p, and more

Logic: always_p, never_p, implies_p, fn_p

Numeric: is_even_p, is_odd_p, is_nan_p, is_inf_p, is_finite_p, pos_p, neg_p, zero_p

Failure explanation

Use explain to get a structured description of why a predicate failed:

from predicate import explain, ge_p, le_p

between = ge_p(2) & le_p(5)
explain(between, 8)
# {'reason': 'Right predicate failed', 'right': {'reason': 'Expected 8 <= 5'}}

Optimizer

Predicate trees can be algebraically simplified:

from predicate import ge_p, le_p, optimize, can_optimize

p = ge_p(2) & le_p(5)
can_optimize(p)  # True (may simplify to a range predicate, etc.)
optimized = optimize(p)

The optimizer handles identities like p & always_true == p, p | always_true == always_true, double-negation elimination, De Morgan's laws, and more.

Compile to native callables

compile_predicate translates a predicate tree into a native Python lambda via AST generation, removing interpreter overhead on hot paths:

from predicate import compile_predicate, ge_p, le_p

between = ge_p(2) & le_p(5)
fast = compile_predicate(between)  # returns a CompiledPredicate

fast(3)  # True  — evaluated by a native lambda: lambda x: x >= 2 and x <= 5
fast(8)  # False

# Introspection is preserved
repr(fast)  # same as repr(between)
fast.explain_failure  # delegates to the original predicate

Use try_compile_predicate to fall back to the original when compilation is not supported (e.g. fn_p, regex_p):

from predicate import try_compile_predicate

safe = try_compile_predicate(some_predicate)  # always returns a callable

Value generation

Predicates can drive property-based testing by generating values that satisfy or violate them:

from predicate import generate_true, generate_false, ge_p, le_p
from more_itertools import take

between = ge_p(2) & le_p(5)

take(5, generate_true(between))  # e.g. [2, 3, 4, 5, 2]
take(5, generate_false(between))  # e.g. [0, 1, 6, 7, -1]

Recursive predicates

Use root_p (or this_p) to define self-referencing predicates over arbitrarily nested structures without writing recursive functions:

from predicate import all_p, is_list_p, is_str_p, root_p

# Matches a string, or a list of strings/lists (recursively)
str_or_nested = is_str_p | (is_list_p & all_p(root_p))

str_or_nested("hello")  # True
str_or_nested(["a", ["b", "c"]])  # True
str_or_nested(["a", 1])  # False

For mutually recursive predicates, use mutual_recur_p.

Runtime instrumentation (Spec)

Instrument functions with predicate-based contracts that are checked at call time:

from predicate import ge_p, instrument, is_int_p, is_str_p, le_p


@instrument({"args": {"x": is_int_p & ge_p(0) & le_p(100)}, "ret": is_str_p})
def grade(x: int) -> str:
    return "pass" if x >= 50 else "fail"


grade(75)  # "pass"
grade(-1)  # raises ValueError: Parameter predicate for function grade failed

You can also instrument all functions in a module or class:

from predicate import instrument_module, instrument_class

instrument_module(my_module)
instrument_class(MyClass)

Specs can include cross-argument constraints via fn or fn_p keys, and expected exception types via raises.

Analysis

Check logical properties of predicates:

from predicate import are_equivalent, is_satisfiable, is_tautology, ge_p, le_p, always_p

is_tautology(always_p)  # True
is_satisfiable(ge_p(5) & le_p(3))  # False (unsatisfiable)
are_equivalent(~~ge_p(2), ge_p(2))  # True

Serialization

Export predicates to multiple formats:

from predicate import ge_p, le_p, to_json, to_yaml, to_dot, to_latex

p = ge_p(2) & le_p(5)

to_json(p)  # JSON string
to_yaml(p)  # YAML string
to_dot(p)  # Graphviz DOT for visualization
to_latex(p)  # LaTeX expression

Deserialize from JSON:

from predicate.formatter.from_json import from_json

p = from_json('{"and": [{"ge": 2}, {"le": 5}]}')

Metadata

Release files for py-predicate 1.9.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for py-predicate 1.9.0
File Size Uploaded Provenance Actions
py_predicate-1.9.0.tar.gz 66.3 kB Without provenance Details for py_predicate-1.9.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for py-predicate 1.9.0
File Interpreter ABI Platform Actions
py_predicate-1.9.0-py3-none-any.whl Python 3 none any Details for py_predicate-1.9.0-py3-none-any.whl

Total release size: 169.2 kB

Release files / py_predicate-1.9.0.tar.gz

Download URL py_predicate-1.9.0.tar.gz
Size 66.3 kB
Tags Source
SHA-256 checksum
How to use checksums
61c53b24599630661a7fcb630a1e1bad56430846fcac8ef39ef197b1c9e483b3
BLAKE2b-256 checksum
How to use checksums
bc551d231fab8856eb9a96049ebc7a1c4e2acf8044c41dc1d4ad34fb02515f66
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.0

Release files / py_predicate-1.9.0-py3-none-any.whl

Download URL py_predicate-1.9.0-py3-none-any.whl
Size 102.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9134b0b9f1bcb9d950a5a9e2f55cf39b5e3c5c0635864f7fa111e89d7f752cf8
BLAKE2b-256 checksum
How to use checksums
7e95b6648eb7640b2684df3760041ddafadef22f838e74b84143b3e7d99079c9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.0

Security for py-predicate 1.9.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page