opa-golib-python-bindings 0.1.2__tar.gz → 0.2.0__tar.gz

{opa_golib_python_bindings-0.1.2 → opa_golib_python_bindings-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: opa-golib-python-bindings
-Version: 0.1.2
+Version: 0.2.0
 Summary: Python bindings for the OPA (Open Policy Agent) Rego engine via a Go c-shared library
 Project-URL: Homepage, https://github.com/phi1010/opa-golib-python-bindings
 Project-URL: Repository, https://github.com/phi1010/opa-golib-python-bindings
@@ -68,6 +68,20 @@ Notes:
 - Builtin arguments and return values are JSON-compatible objects. A callback exception
   becomes an evaluation error; returning is fine.
 - An undefined document raises `OpaUndefinedError`.
+- Pass `coverage=True` to `eval_document` / `eval_query` to capture a coverage
+  report (OPA's `cover` tracer) in `engine.last_coverage`: per-file `covered` /
+  `not_covered` line ranges plus line counts and a coverage percentage over all
+  added policies. Evaluating without `coverage=True` resets it to `None`.
+- Pass `trace=True` to capture the full evaluation trace in `engine.last_trace`:
+  a list of event dicts (`op`, `location`, `node`, `locals`, ...) in evaluation
+  order. `locals` holds the plugged variable bindings live at each step, so the
+  value a statement produced is visible (e.g. `{"x": 6}` after `x := input.n * 2`);
+  a false condition appears as a `Fail` event at its location. An undefined
+  document still carries its trace — the main way to see which condition failed. Note that `node`
+  shows the compiler-rewritten expression (temporaries like `__local0__`), a
+  statement may appear multiple times (`Redo` on backtracking), and tracing
+  slows evaluation, so keep it opt-in per call. Coverage only records *which*
+  statements were evaluated; traces are how to see their results.
 - Rego `print(...)` output is captured per evaluation: set `engine.print_handler`
   to a `callable(message, location)` to receive it (default: written to stderr);
   `engine.last_prints` holds the `(message, location)` pairs of the last eval.

{opa_golib_python_bindings-0.1.2 → opa_golib_python_bindings-0.2.0}/README.md

@@ -43,6 +43,20 @@ Notes:
 - Builtin arguments and return values are JSON-compatible objects. A callback exception
   becomes an evaluation error; returning is fine.
 - An undefined document raises `OpaUndefinedError`.
+- Pass `coverage=True` to `eval_document` / `eval_query` to capture a coverage
+  report (OPA's `cover` tracer) in `engine.last_coverage`: per-file `covered` /
+  `not_covered` line ranges plus line counts and a coverage percentage over all
+  added policies. Evaluating without `coverage=True` resets it to `None`.
+- Pass `trace=True` to capture the full evaluation trace in `engine.last_trace`:
+  a list of event dicts (`op`, `location`, `node`, `locals`, ...) in evaluation
+  order. `locals` holds the plugged variable bindings live at each step, so the
+  value a statement produced is visible (e.g. `{"x": 6}` after `x := input.n * 2`);
+  a false condition appears as a `Fail` event at its location. An undefined
+  document still carries its trace — the main way to see which condition failed. Note that `node`
+  shows the compiler-rewritten expression (temporaries like `__local0__`), a
+  statement may appear multiple times (`Redo` on backtracking), and tracing
+  slows evaluation, so keep it opt-in per call. Coverage only records *which*
+  statements were evaluated; traces are how to see their results.
 - Rego `print(...)` output is captured per evaluation: set `engine.print_handler`
   to a `callable(message, location)` to receive it (default: written to stderr);
   `engine.last_prints` holds the `(message, location)` pairs of the last eval.

{opa_golib_python_bindings-0.1.2 → opa_golib_python_bindings-0.2.0}/go/bridge.go

@@ -21,6 +21,7 @@ import (
 	"unsafe"
 
 	"github.com/open-policy-agent/opa/v1/ast"
+	"github.com/open-policy-agent/opa/v1/cover"
 	"github.com/open-policy-agent/opa/v1/rego"
 	"github.com/open-policy-agent/opa/v1/storage/inmem"
 	"github.com/open-policy-agent/opa/v1/topdown/print"
@@ -187,21 +188,21 @@ func OpaRegisterBuiltin(h C.ulonglong, name *C.char, arity C.int, cb C.opa_callb
 }
 
 //export OpaEvalQuery
-func OpaEvalQuery(h C.ulonglong, query, inputJson *C.char) *C.char {
-	return evalCommon(h, C.GoString(query), inputJson)
+func OpaEvalQuery(h C.ulonglong, query, inputJson *C.char, coverage, trace C.int) *C.char {
+	return evalCommon(h, C.GoString(query), inputJson, coverage != 0, trace != 0)
 }
 
 //export OpaEvalDocument
-func OpaEvalDocument(h C.ulonglong, docPath, inputJson *C.char) *C.char {
+func OpaEvalDocument(h C.ulonglong, docPath, inputJson *C.char, coverage, trace C.int) *C.char {
 	p := C.GoString(docPath)
 	q := "data"
 	if p != "" {
 		q = "data." + p
 	}
-	return evalCommon(h, q, inputJson)
+	return evalCommon(h, q, inputJson, coverage != 0, trace != 0)
 }
 
-func evalCommon(h C.ulonglong, query string, inputJson *C.char) *C.char {
+func evalCommon(h C.ulonglong, query string, inputJson *C.char, coverage, trace bool) *C.char {
 	e, err := getEngine(h)
 	if err != nil {
 		return errorJSON("invalid_handle", err.Error())
@@ -243,11 +244,36 @@ func evalCommon(h C.ulonglong, query string, inputJson *C.char) *C.char {
 	}
 	collector := &printCollector{}
 	evalOpts = append(evalOpts, rego.EvalPrintHook(collector))
+	var cov *cover.Cover
+	if coverage {
+		cov = cover.New()
+		evalOpts = append(evalOpts, rego.EvalQueryTracer(cov))
+	}
+	var tracer *traceCollector
+	if trace {
+		tracer = &traceCollector{}
+		evalOpts = append(evalOpts, rego.EvalQueryTracer(tracer))
+	}
 	rs, err := pq.Eval(context.Background(), evalOpts...)
 	if err != nil {
 		return errorJSON("eval_error", err.Error())
 	}
-	b, err := json.Marshal(map[string]any{"result": rs, "prints": collector.msgs})
+	envelope := map[string]any{"result": rs, "prints": collector.msgs}
+	if cov != nil {
+		e.mu.Lock()
+		parsed := map[string]*ast.Module{}
+		for path, src := range e.modules {
+			if m, perr := ast.ParseModule(path, src); perr == nil {
+				parsed[path] = m
+			}
+		}
+		e.mu.Unlock()
+		envelope["coverage"] = cov.Report(parsed)
+	}
+	if tracer != nil {
+		envelope["trace"] = tracer.events
+	}
+	b, err := json.Marshal(envelope)
 	if err != nil {
 		return errorJSON("internal", err.Error())
 	}

opa_golib_python_bindings-0.2.0/go/trace.go

@@ -0,0 +1,78 @@
+package main
+
+import (
+	"fmt"
+	"strings"
+	"sync"
+
+	"github.com/open-policy-agent/opa/v1/ast"
+	"github.com/open-policy-agent/opa/v1/topdown"
+)
+
+type traceEvent struct {
+	Op       string         `json:"op"`
+	QueryID  uint64         `json:"query_id"`
+	ParentID uint64         `json:"parent_id"`
+	Location string         `json:"location,omitempty"`
+	Node     string         `json:"node,omitempty"`
+	Locals   map[string]any `json:"locals,omitempty"`
+	Message  string         `json:"message,omitempty"`
+}
+
+// traceCollector implements topdown.QueryTracer, capturing every evaluation
+// event together with the local variable bindings live at that point.
+type traceCollector struct {
+	mu     sync.Mutex
+	events []traceEvent
+}
+
+func (t *traceCollector) Enabled() bool { return true }
+
+func (t *traceCollector) Config() topdown.TraceConfig {
+	return topdown.TraceConfig{PlugLocalVars: true}
+}
+
+func (t *traceCollector) TraceEvent(evt topdown.Event) {
+	te := traceEvent{
+		Op:       string(evt.Op),
+		QueryID:  evt.QueryID,
+		ParentID: evt.ParentID,
+		Message:  evt.Message,
+	}
+	if evt.Location != nil {
+		te.Location = evt.Location.String()
+	}
+	if evt.Node != nil {
+		te.Node = fmt.Sprintf("%v", evt.Node)
+	}
+	if evt.Locals != nil {
+		locals := map[string]any{}
+		evt.Locals.Iter(func(k, v ast.Value) bool {
+			kv, ok := k.(ast.Var)
+			if !ok {
+				return false
+			}
+			name := string(kv)
+			// Compiler-generated vars carry the user-facing name in the
+			// event metadata; drop them if no such name exists.
+			if md, found := evt.LocalMetadata[kv]; found {
+				name = string(md.Name)
+			}
+			if strings.HasPrefix(name, "__local") || strings.HasPrefix(name, "$") {
+				return false // compiler temporaries and wildcards
+			}
+			if j, err := ast.JSON(v); err == nil {
+				locals[name] = j
+			} else {
+				locals[name] = v.String()
+			}
+			return false
+		})
+		if len(locals) > 0 {
+			te.Locals = locals
+		}
+	}
+	t.mu.Lock()
+	t.events = append(t.events, te)
+	t.mu.Unlock()
+}

{opa_golib_python_bindings-0.1.2 → opa_golib_python_bindings-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "opa-golib-python-bindings"
-version = "0.1.2"
+version = "0.2.0"
 description = "Python bindings for the OPA (Open Policy Agent) Rego engine via a Go c-shared library"
 readme = "README.md"
 license = "Apache-2.0"

{opa_golib_python_bindings-0.1.2 → opa_golib_python_bindings-0.2.0}/src/opa_bindings/_native.py

@@ -43,9 +43,21 @@ def load():
     ]
 
     lib.OpaEvalQuery.restype = ctypes.c_void_p
-    lib.OpaEvalQuery.argtypes = [ctypes.c_uint64, ctypes.c_char_p, ctypes.c_char_p]
+    lib.OpaEvalQuery.argtypes = [
+        ctypes.c_uint64,
+        ctypes.c_char_p,
+        ctypes.c_char_p,
+        ctypes.c_int,  # coverage
+        ctypes.c_int,  # trace
+    ]
 
     lib.OpaEvalDocument.restype = ctypes.c_void_p
-    lib.OpaEvalDocument.argtypes = [ctypes.c_uint64, ctypes.c_char_p, ctypes.c_char_p]
+    lib.OpaEvalDocument.argtypes = [
+        ctypes.c_uint64,
+        ctypes.c_char_p,
+        ctypes.c_char_p,
+        ctypes.c_int,  # coverage
+        ctypes.c_int,  # trace
+    ]
 
     return lib

{opa_golib_python_bindings-0.1.2 → opa_golib_python_bindings-0.2.0}/src/opa_bindings/engine.py

@@ -50,6 +50,17 @@ class OpaEngine:
         self.print_handler = None
         #: Prints captured by the most recent eval, as (message, location).
         self.last_prints = []
+        #: Coverage report of the most recent eval with ``coverage=True``:
+        #: {"files": {path: {"covered": [...], "not_covered": [...], ...}},
+        #:  "covered_lines": int, "not_covered_lines": int, "coverage": float}.
+        #: None if the last eval did not capture coverage.
+        self.last_coverage = None
+        #: Evaluation trace of the most recent eval with ``trace=True``: a
+        #: list of event dicts {"op", "query_id", "parent_id", "location",
+        #: "node", "locals", "message"} in evaluation order, where "locals"
+        #: holds the variable bindings live at that point. None if the last
+        #: eval did not capture a trace.
+        self.last_trace = None
 
     # -- lifecycle -----------------------------------------------------
 
@@ -90,7 +101,16 @@ class OpaEngine:
             raise OpaError(err.get("code", "unknown"), err.get("message", ""))
         return envelope
 
+    def _eval_reset(self):
+        # Clear per-eval state up front so a failed eval never leaves stale
+        # results from a previous evaluation behind.
+        self.last_coverage = None
+        self.last_trace = None
+        self.last_prints = []
+
     def _eval_result(self, envelope):
+        self.last_coverage = envelope.get("coverage")
+        self.last_trace = envelope.get("trace")
         self.last_prints = [
             (p["message"], p["location"]) for p in envelope.get("prints") or []
         ]
@@ -166,24 +186,50 @@ class OpaEngine:
             del self._functions[name]
             raise
 
-    def eval_query(self, query: str, input=None):
-        """Evaluate a Rego query; returns a list of binding dicts."""
+    def eval_query(
+        self, query: str, input=None, *, coverage: bool = False, trace: bool = False
+    ):
+        """Evaluate a Rego query; returns a list of binding dicts.
+
+        With ``coverage=True`` the evaluation is traced and a coverage report
+        over all added policies is stored in ``self.last_coverage``. With
+        ``trace=True`` the full event trace, including the variable bindings
+        at each step, is stored in ``self.last_trace``.
+        """
         self._check_open()
+        self._eval_reset()
         rs = self._eval_result(
-            self._call(self._lib.OpaEvalQuery, query.encode(), _encode_input(input))
+            self._call(
+                self._lib.OpaEvalQuery,
+                query.encode(),
+                _encode_input(input),
+                int(coverage),
+                int(trace),
+            )
         )
         if not rs:
             return []
         return [r.get("bindings", {}) for r in rs]
 
-    def eval_document(self, path: str, input=None):
+    def eval_document(
+        self, path: str, input=None, *, coverage: bool = False, trace: bool = False
+    ):
         """Evaluate the document at ``data.<path>`` and return its value.
 
-        Raises OpaUndefinedError if the document is undefined.
+        Raises OpaUndefinedError if the document is undefined. With
+        ``coverage=True`` a coverage report is stored in ``self.last_coverage``;
+        with ``trace=True`` the event trace is stored in ``self.last_trace``.
         """
         self._check_open()
+        self._eval_reset()
         rs = self._eval_result(
-            self._call(self._lib.OpaEvalDocument, path.encode(), _encode_input(input))
+            self._call(
+                self._lib.OpaEvalDocument,
+                path.encode(),
+                _encode_input(input),
+                int(coverage),
+                int(trace),
+            )
         )
         if not rs or not rs[0].get("expressions"):
             raise OpaUndefinedError(f"data.{path}" if path else "data")