Pure Python implementation of Google Common Expression Language, https://opensource.google/projects/cel.
The Common Expression Language (CEL) implements common semantics for expression evaluation, enabling different applications to more easily interoperate.
Key Applications
Security policy: organization have complex infrastructure and need common tooling to reason about the system as a whole
Protocols: expressions are a useful data type and require interoperability across programming languages and platforms.
This implementation has minimal dependencies, runs quickly, and can be embedded into Python-based applications. Specifically, the intent is to be part of Cloud Custodian, C7N, as part of the security policy filter.
python -m pip install cel-python
You now have the CEL run-time available to Python-based applications.
CEL specifies that regular expressions use re2 syntax, https://github.com/google/re2/wiki/Syntax. As of the 0.4.0 release, the Google-RE2 module is part of the CEL distribution.
We can read JSON directly from stdin, making this a bit like jq.
% python -m celpy '.this.from.json * 3 + 3' <<EOF
heredoc> {"this": {"from": {"json": 13}}}
heredoc> EOF
42
It's also a desk calculator, like expr, but with float values:
% python -m celpy -n '355.0 / 113.0' 3.1415929203539825
It's not as sophistcated as bc.
But, yes, this has a tiny advantage over python -c '355/113'. Most notably, the ability
to embed Google CEL into other contexts where you don't really want Python's power.
It's also capable of decision-making, like test:
% echo '{"status": 3}' | python -m celpy -sb '.status == 0'
false
% echo $?
1
We can provide a -a option to define objects with specific data types.
This is particularly helpful for providing protobuf message definitions.
python -m celpy -n --arg x:int=6 --arg y:int=7 'x*y' 42
If you want to see details of evaluation, use -v.
python -m celpy -v -n '[2, 4, 6].map(n, n/2)' ... a lot of output [1, 2, 3]
To follow the pattern defined in the Go implementation, there's a multi-step process for compiling a CEL expression to create a runnable "program". This program can then be applied to argument values.
>>> import celpy
>>> cel_source = """
... account.balance >= transaction.withdrawal
... || (account.overdraftProtection
... && account.overdraftLimit >= transaction.withdrawal - account.balance)
... """
>>> env = celpy.Environment()
>>> ast = env.compile(cel_source)
>>> prgm = env.program(ast)
>>> context = {
... "account": celpy.json_to_cel({"balance": 500, "overdraftProtection": False}),
... "transaction": celpy.json_to_cel({"withdrawal": 600})
... }
>>> result = prgm.evaluate(context)
>>> result
BoolType(False)
The Python classes are generally based on the object model in https://github.com/google/cel-go
These types semantics are slightly different from Python's native semantics.
Type coercion is not generally done.
Python // truncates toward negative infinity. Go (and CEL) / truncates toward zero.
The parser is based on the grammars used by Go and C++, but processed through Python Lark.
See https://github.com/google/cel-spec/blob/master/doc/langdef.md
https://github.com/google/cel-cpp/blob/master/parser/Cel.g4
https://github.com/google/cel-go/blob/master/parser/gen/CEL.g4
The documentation includes PlantUML diagrams.
The Sphinx conf.py provides the location for the PlantUML local JAR file if one is used.
Currently, it expects docs/plantuml-asl-1.2025.3.jar.
The JAR is not provided in this repository, get one from https://plantuml.com.
If you install a different version, update the conf.py to refer to the JAR file you've downloaded.
CEL provides a number of runtime errors that are mapped to Python exceptions.
no_matching_overload: this function has no overload for the types of the arguments.no_such_field: a map or message does not contain the desired field.return error for overflow: integer arithmetic overflows
There are mapped to Python celpy.evaluation.EvalError exception. The args will have
a message similar to the CEL error message, as well as an underlying Python exception.
In principle CEL can pre-check types. However, see https://github.com/google/cel-spec/blob/master/doc/langdef.md#gradual-type-checking. Rather than try to pre-check types, we'll rely on Python's implementation.
Here's an example with some details:
>>> import celpy
# A list of type names and class bindings used to create an environment.
>>> types = []
>>> env = celpy.Environment(types)
# Parse the code to create the CEL AST.
>>> ast = env.compile("355. / 113.")
# Use the AST and any overriding functions to create an executable program.
>>> functions = {}
>>> prgm = env.program(ast, functions)
# Variable bindings.
>>> activation = {}
# Final evaluation.
>>> try:
... result = prgm.evaluate(activation)
... error = None
... except CELEvalError as ex:
... result = None
... error = ex.args[0]
>>> result # doctest: +ELLIPSIS
DoubleType(3.14159...)
See https://github.com/google/cel-go/blob/master/examples/simple_test.go
The model Go we're sticking close to:
d := cel.Declarations(decls.NewVar("name", decls.String))
env, err := cel.NewEnv(d)
if err != nil {
log.Fatalf("environment creation error: %v\\n", err)
}
ast, iss := env.Compile(`"Hello world! I'm " + name + "."`)
// Check iss for compilation errors.
if iss.Err() != nil {
log.Fatalln(iss.Err())
}
prg, err := env.Program(ast)
if err != nil {
log.Fatalln(err)
}
out, _, err := prg.Eval(map[string]interface{}{
"name": "CEL",
})
if err != nil {
log.Fatalln(err)
}
fmt.Println(out)
// Output:Hello world! I'm CEL.
Here's the Pythonic approach, using concept patterned after the Go implementation:
>>> from celpy import *
>>> decls = {"name": celtypes.StringType}
>>> env = Environment(annotations=decls)
>>> ast = env.compile('"Hello world! I\'m " + name + "."')
>>> out = env.program(ast).evaluate({"name": "CEL"})
>>> print(out)
Hello world! I'm CEL.
See https://cloudcustodian.io/docs/contribute.html
This project adheres to the Open Code of Conduct. By participating, you are expected to honor this code.