Add Context.set_variable_resolver for lazy variable resolution

Exposes cel 0.13's VariableResolver trait to Python. The callback is
invoked with a variable name and returns the value (or None to fall
through to variables registered via add_variable). Useful for
contexts backed by databases, lazily-loaded config files, or other
sources where materializing every variable upfront is wasteful.

Exceptions from the callback are logged and treated as "not handled"
rather than propagated to the caller.

Refs #22

Author: hardbyte

CHANGELOG.md

@@ -13,6 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- `Context.set_variable_resolver(callback)` exposes cel 0.13's `VariableResolver` trait to Python. The callback receives a variable name and returns the value (or `None` to fall through to variables registered with `add_variable`). Useful for backing a CEL context with on-demand sources (database lookups, lazily-loaded config files, etc.) without materializing the full set of variables upfront. Exceptions raised by the resolver are logged and treated as "not handled".
 - Idiomatic Python exception mapping for several CEL runtime errors that previously fell through to `ValueError`:
   - Arithmetic overflow → `OverflowError` (e.g. `9223372036854775807 + 1`, including the new overflow-safe int math in cel 0.13).
   - Division by zero / modulo by zero → `ZeroDivisionError`.

python/cel/cel.pyi

@@ -26,6 +26,14 @@ class Context:
         """Add a function to the context."""
         ...
 
+    def set_variable_resolver(self, resolver: Callable[[str], Any]) -> None:
+        """Register a callback for lazy variable resolution.
+
+        The callback receives a variable name and returns the value, or None
+        to fall through to variables added via add_variable().
+        """
+        ...
+
     def update(self, variables: Dict[str, Any]) -> None:
         """Update context with variables from a dictionary."""
         ...

src/context.rs

@@ -43,6 +43,9 @@ use std::collections::HashMap;
 pub struct Context {
     pub variables: HashMap<String, Value>,
     pub functions: HashMap<String, Py<PyAny>>,
+    /// Optional Python callable for lazy variable resolution. Invoked with a
+    /// variable name; returns the value (or None to fall through to `variables`).
+    pub resolver: Option<Py<PyAny>>,
 }
 
 #[pyo3::pymethods]
@@ -122,6 +125,7 @@ impl Context {
         let mut context = Context {
             variables: HashMap::new(),
             functions: HashMap::new(),
+            resolver: None,
         };
 
         if let Some(variables) = variables {
@@ -203,6 +207,42 @@ impl Context {
         self.functions.insert(name, function);
     }
 
+    /// Registers a Python callable for lazy variable resolution.
+    ///
+    /// When evaluating an expression, CEL will call `resolver(name)` for each
+    /// unbound variable name encountered. The callback should return the value
+    /// (any Python type convertible to a CEL value) or `None` to fall through
+    /// to variables registered with `add_variable`.
+    ///
+    /// This is useful when materializing the full set of variables up front is
+    /// expensive — for example, a dict-like backed by a database, filesystem,
+    /// or remote API where you only want to fetch values the expression
+    /// actually references.
+    ///
+    /// Args:
+    ///     resolver (Callable[[str], Any]): Function that takes a variable name
+    ///         and returns the value or None.
+    ///
+    /// Notes:
+    ///     - The resolver is consulted *before* explicitly-registered variables.
+    ///       Return None from the resolver to delegate to those.
+    ///     - Exceptions raised by the resolver are logged and treated as None.
+    ///     - The callback is invoked from Rust holding the GIL; keep it simple
+    ///       and avoid blocking on long-running I/O if possible.
+    ///
+    /// Example:
+    ///     >>> from cel import Context, evaluate
+    ///     >>> store = {"user": {"name": "Alice", "age": 30}}
+    ///     >>> def lookup(name):
+    ///     ...     return store.get(name)
+    ///     >>> ctx = Context()
+    ///     >>> ctx.set_variable_resolver(lookup)
+    ///     >>> evaluate("user.name", ctx)
+    ///     'Alice'
+    fn set_variable_resolver(&mut self, resolver: Py<PyAny>) {
+        self.resolver = Some(resolver);
+    }
+
     /// Adds a variable to the context.
     ///
     /// Variables added to the context become available for use in CEL expressions.

src/lib.rs

@@ -1,5 +1,6 @@
 mod context;
 
+use ::cel::context::VariableResolver;
 use ::cel::objects::{Key, OptionalValue, TryIntoValue};
 use ::cel::{Context as CelContext, ExecutionError, Program, Value};
 use log::warn;
@@ -319,13 +320,50 @@ impl<'a> RustyPyType<'a> {
     }
 }
 
+/// Bridges a Python callable to cel-rust's `VariableResolver` trait so users
+/// can resolve variables lazily on demand instead of materializing them up front.
+///
+/// The callback receives the variable name as a string and returns either a
+/// supported Python value or `None` (meaning "not handled — fall back to the
+/// statically-defined variables map"). Any exception raised by the callback
+/// is treated as "not handled" and a warning is logged.
+struct PyVariableResolver {
+    callback: Py<PyAny>,
+}
+
+impl VariableResolver for PyVariableResolver {
+    fn resolve(&self, variable: &str) -> Option<Value> {
+        Python::attach(|py| {
+            let result = match self.callback.call1(py, (variable,)) {
+                Ok(r) => r,
+                Err(e) => {
+                    warn!("Variable resolver raised for '{variable}': {e}");
+                    return None;
+                }
+            };
+            if result.is_none(py) {
+                return None;
+            }
+            let bound = result.bind(py);
+            match RustyPyType(bound).try_into_value() {
+                Ok(v) => Some(v),
+                Err(e) => {
+                    warn!("Variable resolver for '{variable}' returned an unsupported value: {e}");
+                    None
+                }
+            }
+        })
+    }
+}
+
 /// Build a CEL execution environment from an optional evaluation context.
 ///
 /// This consolidates the shared logic used by `evaluate()` and `Program.execute()`
 /// to keep behavior consistent between the two entrypoints.
-fn build_environment(
+fn build_environment<'r>(
     evaluation_context: Option<&Bound<'_, PyAny>>,
-    environment: &mut CelContext<'_>,
+    environment: &mut CelContext<'r>,
+    resolver_out: &'r mut Option<PyVariableResolver>,
 ) -> PyResult<()> {
     let mut ctx = context::Context::new(None, None)?;
 
@@ -336,6 +374,11 @@ fn build_environment(
             // Clone variables and functions into our local Context
             ctx.variables = py_context_ref.variables.clone();
             ctx.functions = py_context_ref.functions.clone();
+            if let Some(cb) = py_context_ref.resolver.as_ref() {
+                *resolver_out = Some(PyVariableResolver {
+                    callback: Python::attach(|py| cb.clone_ref(py)),
+                });
+            }
         } else if let Ok(py_dict) = evaluation_context.cast::<PyDict>() {
             // User passed in a dict - let's process variables and functions from the dict
             ctx.update(py_dict)?;
@@ -417,6 +460,13 @@ fn build_environment(
         }
     }
 
+    // Attach the lazy resolver if one was provided. The resolver lives in
+    // `*resolver_out` (caller-owned), and the cel::Context borrows it for
+    // its lifetime `'r`.
+    if let Some(resolver) = resolver_out.as_ref() {
+        environment.set_variable_resolver(resolver);
+    }
+
     Ok(())
 }
 
@@ -748,7 +798,8 @@ impl TryIntoValue for RustyPyType<'_> {
 #[pyfunction(signature = (src, evaluation_context=None))]
 fn evaluate(src: String, evaluation_context: Option<&Bound<'_, PyAny>>) -> PyResult<RustyCelType> {
     let mut environment = CelContext::default();
-    build_environment(evaluation_context, &mut environment)?;
+    let mut resolver_slot: Option<PyVariableResolver> = None;
+    build_environment(evaluation_context, &mut environment, &mut resolver_slot)?;
 
     // Use panic::catch_unwind to handle parser panics gracefully
     let program = panic::catch_unwind(|| Program::compile(&src))
@@ -784,7 +835,8 @@ fn execute_compiled_program(
     evaluation_context: Option<&Bound<'_, PyAny>>,
 ) -> PyResult<Py<PyAny>> {
     let mut environment = CelContext::default();
-    build_environment(evaluation_context, &mut environment)?;
+    let mut resolver_slot: Option<PyVariableResolver> = None;
+    build_environment(evaluation_context, &mut environment, &mut resolver_slot)?;
 
     // Use panic::catch_unwind to handle execution panics gracefully
     // AssertUnwindSafe is needed because the environment contains function closures

tests/test_context.py

@@ -107,3 +107,82 @@ def test_nested_context_none():
     assert cel.evaluate("spec.host", cel_context) == "github.com"
     assert cel.evaluate("data['response-code']", cel_context) == "NOERROR"
     assert cel.evaluate("size(data.A)", cel_context) == 1
+
+
+class TestVariableResolver:
+    """Tests for lazy variable resolution via set_variable_resolver."""
+
+    def test_resolver_supplies_variable(self):
+        """Resolver callback can provide variables not registered statically."""
+        ctx = cel.Context()
+        ctx.set_variable_resolver(
+            lambda name: {"name": "Alice", "age": 30} if name == "user" else None
+        )
+        assert cel.evaluate("user.name", ctx) == "Alice"
+        assert cel.evaluate("user.age", ctx) == 30
+
+    def test_resolver_is_called_lazily(self):
+        """Resolver only fires for names the expression actually references."""
+        accessed = []
+
+        def lookup(name):
+            accessed.append(name)
+            return {"limit": 50}.get(name)
+
+        ctx = cel.Context()
+        ctx.set_variable_resolver(lookup)
+        assert cel.evaluate("limit > 10", ctx) is True
+        assert accessed == ["limit"]
+
+    def test_resolver_none_falls_through_to_static_variables(self):
+        """Returning None from the resolver delegates to add_variable()-registered values."""
+        ctx = cel.Context(variables={"static_var": 42})
+        ctx.set_variable_resolver(lambda name: None)
+        assert cel.evaluate("static_var", ctx) == 42
+
+    def test_resolver_undefined_raises(self):
+        """When neither the resolver nor static variables supply a name, evaluate raises."""
+        ctx = cel.Context()
+        ctx.set_variable_resolver(lambda name: None)
+        with pytest.raises(RuntimeError, match="Undefined variable or function"):
+            cel.evaluate("missing", ctx)
+
+    def test_resolver_exception_is_swallowed(self):
+        """An exception from the resolver is treated as 'not handled' rather than propagated."""
+        ctx = cel.Context(variables={"x": 7})
+
+        def explosive(name):
+            raise ValueError(f"boom on {name}")
+
+        ctx.set_variable_resolver(explosive)
+        # Falls through to the static variable
+        assert cel.evaluate("x", ctx) == 7
+
+    def test_resolver_works_with_compiled_program(self):
+        """Resolver applies through compile()+execute(), not just evaluate()."""
+        program = cel.compile("user.name")
+        ctx = cel.Context()
+        ctx.set_variable_resolver(lambda name: {"name": "Bob"} if name == "user" else None)
+        assert program.execute(ctx) == "Bob"
+
+    def test_resolver_returns_various_types(self):
+        """Resolver values can be any supported Python type."""
+
+        def lookup(name):
+            return {
+                "i": 42,
+                "f": 3.14,
+                "s": "hello",
+                "b": True,
+                "l": [1, 2, 3],
+                "m": {"k": "v"},
+            }.get(name)
+
+        ctx = cel.Context()
+        ctx.set_variable_resolver(lookup)
+        assert cel.evaluate("i", ctx) == 42
+        assert cel.evaluate("f", ctx) == 3.14
+        assert cel.evaluate("s", ctx) == "hello"
+        assert cel.evaluate("b", ctx) is True
+        assert cel.evaluate("size(l)", ctx) == 3
+        assert cel.evaluate("m.k", ctx) == "v"