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 SpecViolationError: Parameter predicate for parameter 'x' of 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.

To turn all checks off without removing the decorators, set PREDICATE_INSTRUMENT=0 or call set_instrumentation(False).

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.11.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.11.0
File Size Uploaded Provenance Actions
py_predicate-1.11.0.tar.gz 97.3 kB Without provenance Details for py_predicate-1.11.0.tar.gz

Built distribution (wheel)

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

Total release size: 237.3 kB

Release files / py_predicate-1.11.0.tar.gz

Download URL py_predicate-1.11.0.tar.gz
Size 97.3 kB
Tags Source
SHA-256 checksum
How to use checksums
3559e3c4e24a38aaabb985bb9eac80bca8e9b51b1b0c41543e64a2783d025336
BLAKE2b-256 checksum
How to use checksums
fb3e0837d156084c066b396fe6177c9f05fe11eacd672a1ce9460fec11294141
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.9

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

Download URL py_predicate-1.11.0-py3-none-any.whl
Size 140.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ff9532bc49ed7dfcc9fb1a236735b655c64bf5e740a9d9017e0e7e666fa05470
BLAKE2b-256 checksum
How to use checksums
3a6de828f769b11449f18c5d20c7cc7b597eb322f58a8a18d78295e60e29f484
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.9

Security for py-predicate 1.11.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