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.10.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| py_predicate-1.10.0.tar.gz | 72.4 kB | Without provenance | Details for py_predicate-1.10.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| py_predicate-1.10.0-py3-none-any.whl | Python 3 | none | any | Details for py_predicate-1.10.0-py3-none-any.whl |
Total release size: 184.7 kB
Release files / py_predicate-1.10.0.tar.gz
| Download URL | py_predicate-1.10.0.tar.gz |
|---|---|
| Size | 72.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
32768163d41f99d935f5b3e3d636d733c21b6cc424ad7730f2a6d66c50b33ab5
|
|
BLAKE2b-256 checksum How to use checksums |
fad9b445be2907f2e614df51646ef93d24aeed7671b1ac0b6165e44c0d3b52d3
|
| 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.10.0-py3-none-any.whl
| Download URL | py_predicate-1.10.0-py3-none-any.whl |
|---|---|
| Size | 112.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6bea887205d491a6c59f36172f5a31a3371d0da57743a5110ea5baecfa46221d
|
|
BLAKE2b-256 checksum How to use checksums |
1fe6e4d55e22bb693a4aef4ab99a682b534964f69512bd06e82c7464f9fc72a0
|
| 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.10.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.