Issue 107 (cloud-custodian#118)

Add Transpiler capability, and an additional benchmark.

Update the documentation significantly.

Update some sketchy design features, also.
Most notably. `celtypes.TypeType` should **not** have created types from their string names.

Eliminate a test case that doesn't apply to all versions.

Author: slott56

.gitignore

@@ -134,3 +134,6 @@ type_check/lineprecision.txt
 demo/issue_41.py
 demo/issue_80.py
 setup.sh
+/docs/build/doctrees
+docs/build/html/.buildinfo
+docs/build/html/.buildinfo.bak

.travis.yml

@@ -21,35 +21,30 @@ build:
 	uv build
 
 install-tools:
-	cd tools && export PATH="/usr/local/go/bin:/usr/local/bin:$PATH" && go mod init mkgherkin && go mod tidy
+	cd tools && docker pull golang && docker build -t mkgherkin .
 
 test:
 	cd features && $(MAKE) all
-	tox -e py312
+	tox run -e py312
 
 test-all:
 	cd features && $(MAKE) all
-	tox
+	tox run
 
 test-wip:
 	cd features && $(MAKE) all
-	tox -e wip
+	tox run -e wip
 
 test-tools:
-	tox -e tools
+	tox run -e tools
 	cd features && $(MAKE) scan
 
-unit-test:
-	PYTHONPATH=src python -m pytest -vv --cov=src --cov-report=term-missing ${test}
-	PYTHONPATH=src python -m doctest tools/*.py
-	PYTHONPATH=src python -m doctest features/steps/*.py
-
 docs: $(wildcard docs/source/*.rst)
 	PYTHONPATH=src python -m doctest docs/source/*.rst
 	export PYTHONPATH=$(PWD)/src:$(PWD)/tools && cd docs && $(MAKE) html
 
 lint:
-	tox -e lint
+	tox run -e lint
 
 coverage:
 	coverage report -m

Makefile

@@ -128,11 +128,11 @@ can then be applied to argument values.
     >>> ast = env.compile(cel_source)
     >>> prgm = env.program(ast)
 
-    >>> activation = {
+    >>> context = {
     ...     "account": celpy.json_to_cel({"balance": 500, "overdraftProtection": False}),
     ...     "transaction": celpy.json_to_cel({"withdrawal": 600})
     ... }
-    >>> result = prgm.evaluate(activation)
+    >>> result = prgm.evaluate(context)
     >>> result
     BoolType(False)
 
@@ -153,10 +153,15 @@ 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.
+
 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.
@@ -171,6 +176,79 @@ However, see https://github.com/google/cel-spec/blob/master/doc/langdef.md#gradu
 Rather than try to pre-check types, we'll rely on Python's implementation.
 
 
+Example 2
+=========
+
+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...)
+
+Example 3
+=========
+
+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.
+
+
 Contributing
 ============
 

README.rst

@@ -351,8 +351,8 @@
     "none": lambda optional, : None
 }
 
-def simple_performance():
-    env = celpy.Environment()
+def simple_performance(runner_class: type[celpy.Runner] | None = None) -> None:
+    env = celpy.Environment(runner_class=runner_class)
 
     number = 100
     compile = timeit.timeit(
@@ -364,8 +364,8 @@ def simple_performance():
             'CEL_EXPRESSION_ORIGINAL_NO_OPTIONAL': CEL_EXPRESSION_ORIGINAL_NO_OPTIONAL
         },
         number=number
-    ) / number
-    print(f"Compile:  {1_000 * compile:9.4f} ms")
+    )
+    print(f"Compile:  {1_000 * compile / number:9.4f} ms")
 
     ast = env.compile(CEL_EXPRESSION_ORIGINAL_NO_OPTIONAL)
 
@@ -380,8 +380,8 @@ def simple_performance():
             'functions': functions
         },
         number=number
-    ) / number
-    print(f"Prepare:  {1_000 * prepare:9.4f} ms")
+    )
+    print(f"Prepare:  {1_000 * prepare / number:9.4f} ms")
 
     program = env.program(ast, functions=functions)
 
@@ -398,8 +398,8 @@ def simple_performance():
         """),
         globals={'celpy': celpy},
         number=number
-    ) / number
-    print(f"Convert:  {1_000 * convert:9.4f} ms")
+    )
+    print(f"Convert:  {1_000 * convert / number:9.4f} ms")
 
     cel_context = {
         "class_a": celpy.json_to_cel({"property_a": "something"}),
@@ -419,8 +419,8 @@ def simple_performance():
             'cel_context': cel_context
         },
         number=number
-    ) / number
-    print(f"Evaluate: {1_000 * evaluation:9.4f} ms")
+    )
+    print(f"Evaluate: {1_000 * evaluation / number:9.4f} ms")
 
     print()
 
@@ -450,7 +450,18 @@ def detailed_profile():
     ps.print_stats()
 
 def main():
-    simple_performance()
+    print("# Performance")
+    print()
+    print("## Interpreter")
+    print()
+    simple_performance(celpy.InterpretedRunner)
+    print()
+    print("## Transpiler")
+    print()
+    simple_performance(celpy.CompiledRunner)
+    print()
+    print("# Profile")
+    print()
     detailed_profile()
 
 if __name__ == "__main__":