Common Expression Language

0.5.6 verified Fri May 01 auth: no python

Python bindings for the Common Expression Language (CEL), providing evaluation, compilation, and CLI tools. Current version 0.5.6, requires Python >=3.11. Development is active with regular releases.

pip install common-expression-language

Common errors

error ModuleNotFoundError: No module named 'cel' ↓

cause Package is installed as 'common-expression-language' but imported as 'cel'.

fix

Install with pip install common-expression-language and then from cel import evaluate.

error ValueError: Unsupported type: <class '...'> ↓

cause CEL cannot convert some Python types (e.g., custom objects) to CEL values.

fix

Convert unsupported types to supported ones (int, float, str, bool, list, dict, None) before passing to evaluate().

error cel.exceptions.EvaluationError: ... ↓

cause CEL expression syntax error or type mismatch during evaluation.

fix

Check expression syntax: ensure operators and function calls are valid CEL. Use cel.parse() to validate syntax separately.

Warnings

gotcha Python types may be automatically converted to CEL types. Be cautious with dictionaries: dict subclasses are now properly handled (v0.5.6), but avoid relying on insertion order preservation in older versions. ↓

fix Upgrade to >=0.5.6 for dict subclass support.

breaking Rust API breaking change in v0.5.0: cel-interpreter crate renamed to cel, function registration changed. Python API unaffected. ↓

fix No action needed for Python users; Rust bindings must update imports from cel_interpreter:: to cel:: and use IntoFunction trait.

gotcha Optional values are surfaced as cel.OptionalValue objects (since v0.5.5) instead of debug strings. Code relying on string output may break. ↓

fix Use .value property or isinstance() checks for OptionalValue.

gotcha The cel CLI command may conflict with other packages. On some systems, it might be shadowed by another executable named 'cel'. ↓

fix Call via python -m cel or check with `which cel`.

Imports

evaluate

wrong

from common_expression_language import evaluate

correct

from cel import evaluate

Package name is 'cel', not 'common_expression_language'

Quickstart

Basic usage: evaluate CEL expressions with optional context and custom functions.

from cel import evaluate

# Evaluate a simple expression
result = evaluate("1 + 2")
print(result)  # 3

# With a context
context = {"age": 18}
result = evaluate("age > 21", context)
print(result)  # False

# Use custom Python functions
def is_adult(age):
    return age > 21

context = {"is_adult": is_adult, "age": 18}
result = evaluate("is_adult(age)", context)
print(result)  # False