1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
|
Metadata-Version: 2.1
Name: cel-python
Version: 0.2.0
Summary: Pure Python implementation of Google Common Expression Language
License: LICENSE.txt
Author: S. Lott
Author-email: slott56@gmail.com
Requires-Python: >=3.8,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: jmespath (>=1.0.1,<2.0.0)
Requires-Dist: lark (>=0.12.0,<0.13.0)
Requires-Dist: python-dateutil (>=2.9.0.post0,<3.0.0)
Requires-Dist: pyyaml (>=6.0.1,<7.0.0)
Requires-Dist: types-python-dateutil (>=2.9.0.20240316,<3.0.0.0)
Requires-Dist: types-pyyaml (>=6.0.12.20240311,<7.0.0.0)
Description-Content-Type: text/x-rst
##########
cel-python
##########
.. image:: https://img.shields.io/pypi/v/cel-python.svg
:target: https://pypi.org/projects/cel-python/
:alt: PyPI: cel-python
.. image:: https://github.com/cloud-custodian/cel-python/workflows/CI/badge.svg
:target: https://github.com/cloud-custodian/cel-python/actions
:alt: GitHub Actions Build Status
.. image:: https://img.shields.io/badge/license-Apache%202-blue.svg
:target: https://www.apache.org/licenses/LICENSE-2.0
:alt: Apache License
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.
Installation
=============
::
pip install cel-python
You now have the CEL run-time available to Python-based applications.
Command Line
============
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]
Library
=======
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)
>>> activation = {
... "account": celpy.json_to_cel({"balance": 500, "overdraftProtection": False}),
... "transaction": celpy.json_to_cel({"withdrawal": 600})
... }
>>> result = prgm.evaluate(activation)
>>> 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.
Development
===========
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
Notes
=====
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.
Contributing
============
See https://cloudcustodian.io/docs/contribute.html
Code of Conduct
===============
This project adheres to the `Open Code of Conduct <https://developer.capitalone.com/resources/code-of-conduct>`_. By
participating, you are expected to honor this code.
|
