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

opa_golib_python_bindings-0.3.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.5
+Name: opa-golib-python-bindings
+Version: 0.3.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
+Project-URL: Issues, https://github.com/phi1010/opa-golib-python-bindings/issues
+Author: Phillip Kuhrt
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: authorization,opa,open-policy-agent,policy,rego
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Go
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.14
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pyyaml; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# opa-golib-python-bindings
+
+Python bindings for the [OPA](https://www.openpolicyagent.org/) Rego engine, embedding
+`github.com/open-policy-agent/opa/v1/rego` via a Go c-shared library and a stdlib-only
+ctypes wrapper.
+
+## Build
+
+Requires Go >= 1.26 and Python >= 3.14.
+
+```sh
+make build   # builds src/opa_bindings/libopabridge.so
+make test    # builds + runs pytest
+```
+
+## Usage
+
+```python
+from opa_bindings import OpaEngine
+
+users = {"alice": {"role": "admin"}}
+
+with OpaEngine() as engine:
+    engine.add_policy("authz.rego", """
+package authz
+
+allow if lookup_user(input.user).role == "admin"
+""")
+    engine.add_data({"admin": ["alice"]}, path="roles")   # deep-merged; conflicts raise
+    engine.register_function("lookup_user", lambda name: users.get(name))
+
+    engine.eval_document("authz.allow", {"user": "alice"})  # -> True
+    engine.eval_query("x = data.roles.admin[_]")            # -> [{"x": "alice"}]
+```
+
+Notes:
+
+- `add_data` deep-merges objects; identical values coexist, conflicting values raise
+  `OpaError(code="merge_conflict")` naming the conflicting path.
+- `register_function` infers arity from the callable's signature. A `*args` function is
+  variadic and is called from Rego with a single array argument: `many(["a", "b"])`
+  (OPA does not support variadic builtins with return values).
+- 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.
+- `compile_filters` partially evaluates a query and translates the residual
+  policy into a data filter (OPA's Compile-API / data-filter machinery):
+
+  ```python
+  engine.add_policy("filters.rego", """
+  package filters
+
+  include if input.fruits.colour == "green"
+  include if {
+      input.fruits.name == "banana"
+      input.user == "admin"
+  }
+  """)
+  engine.compile_filters(
+      "data.filters.include",
+      {"user": "admin"},              # known input
+      unknowns=["input.fruits"],      # left symbolic
+      target="sql", dialect="postgresql",
+  )
+  # -> {"query": "WHERE (fruits.colour = E'green' OR fruits.name = E'banana')",
+  #     "masks": None}
+  ```
+
+  `target="sql"` (dialects `postgresql`, `mysql`, `sqlserver`, `sqlite`)
+  yields a WHERE clause string; `target="ucast"` (dialects `all`, `prisma`,
+  `linq`, or `""`) yields a UCAST condition dict (the `ucast.json` wire
+  format). `query` is `None` when the policy can never match and `""`/`{}`
+  when it always matches. `mappings` renames tables/columns (e.g.
+  `{"fruits": {"$self": "fruit_table", "colour": "col"}}`), and `mask_rule`
+  names a rule evaluated to produce column masks (returned under `"masks"`).
+  Residual conditions that cannot be expressed for the chosen target raise
+  `OpaError(code="compile_error")`.
+
+  Unknown refs must have the shape `input.<table>.<column>` — exactly two
+  segments after `input`, whatever the declared unknown boundary is, and for
+  every target/dialect (`ucast`/`all` included; `mappings` cannot deepen it).
+  So `unknowns=["input.item"]` permits only `input.item.<column>`, while the
+  bare `unknowns=["input"]` permits `input.<table>.<column>`. Deeper refs
+  like `input.item.attrs.price.value` fail with `pe_fragment_error: invalid
+  ref operand`, so nested documents (e.g. an EAV entity with per-attribute
+  type/value objects, or per-locale value objects) must be flattened into
+  columns (`input.attr.value_number`, `input.attr.value_de`, ...). Dynamic
+  column choice is fine as long as the key is known at compile time:
+  `input.attr[sprintf("value_%s", [input.locale])]` resolves to a single
+  column during partial evaluation.
+- 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.3.0/README.md

@@ -0,0 +1,107 @@
+# opa-golib-python-bindings
+
+Python bindings for the [OPA](https://www.openpolicyagent.org/) Rego engine, embedding
+`github.com/open-policy-agent/opa/v1/rego` via a Go c-shared library and a stdlib-only
+ctypes wrapper.
+
+## Build
+
+Requires Go >= 1.26 and Python >= 3.14.
+
+```sh
+make build   # builds src/opa_bindings/libopabridge.so
+make test    # builds + runs pytest
+```
+
+## Usage
+
+```python
+from opa_bindings import OpaEngine
+
+users = {"alice": {"role": "admin"}}
+
+with OpaEngine() as engine:
+    engine.add_policy("authz.rego", """
+package authz
+
+allow if lookup_user(input.user).role == "admin"
+""")
+    engine.add_data({"admin": ["alice"]}, path="roles")   # deep-merged; conflicts raise
+    engine.register_function("lookup_user", lambda name: users.get(name))
+
+    engine.eval_document("authz.allow", {"user": "alice"})  # -> True
+    engine.eval_query("x = data.roles.admin[_]")            # -> [{"x": "alice"}]
+```
+
+Notes:
+
+- `add_data` deep-merges objects; identical values coexist, conflicting values raise
+  `OpaError(code="merge_conflict")` naming the conflicting path.
+- `register_function` infers arity from the callable's signature. A `*args` function is
+  variadic and is called from Rego with a single array argument: `many(["a", "b"])`
+  (OPA does not support variadic builtins with return values).
+- 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.
+- `compile_filters` partially evaluates a query and translates the residual
+  policy into a data filter (OPA's Compile-API / data-filter machinery):
+
+  ```python
+  engine.add_policy("filters.rego", """
+  package filters
+
+  include if input.fruits.colour == "green"
+  include if {
+      input.fruits.name == "banana"
+      input.user == "admin"
+  }
+  """)
+  engine.compile_filters(
+      "data.filters.include",
+      {"user": "admin"},              # known input
+      unknowns=["input.fruits"],      # left symbolic
+      target="sql", dialect="postgresql",
+  )
+  # -> {"query": "WHERE (fruits.colour = E'green' OR fruits.name = E'banana')",
+  #     "masks": None}
+  ```
+
+  `target="sql"` (dialects `postgresql`, `mysql`, `sqlserver`, `sqlite`)
+  yields a WHERE clause string; `target="ucast"` (dialects `all`, `prisma`,
+  `linq`, or `""`) yields a UCAST condition dict (the `ucast.json` wire
+  format). `query` is `None` when the policy can never match and `""`/`{}`
+  when it always matches. `mappings` renames tables/columns (e.g.
+  `{"fruits": {"$self": "fruit_table", "colour": "col"}}`), and `mask_rule`
+  names a rule evaluated to produce column masks (returned under `"masks"`).
+  Residual conditions that cannot be expressed for the chosen target raise
+  `OpaError(code="compile_error")`.
+
+  Unknown refs must have the shape `input.<table>.<column>` — exactly two
+  segments after `input`, whatever the declared unknown boundary is, and for
+  every target/dialect (`ucast`/`all` included; `mappings` cannot deepen it).
+  So `unknowns=["input.item"]` permits only `input.item.<column>`, while the
+  bare `unknowns=["input"]` permits `input.<table>.<column>`. Deeper refs
+  like `input.item.attrs.price.value` fail with `pe_fragment_error: invalid
+  ref operand`, so nested documents (e.g. an EAV entity with per-attribute
+  type/value objects, or per-locale value objects) must be flattened into
+  columns (`input.attr.value_number`, `input.attr.value_de`, ...). Dynamic
+  column choice is fine as long as the key is known at compile time:
+  `input.attr[sprintf("value_%s", [input.locale])]` resolves to a single
+  column during partial evaluation.
+- 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.3.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.3.0/go/compile.go

@@ -0,0 +1,106 @@
+package main
+
+/*
+#include <stdlib.h>
+*/
+import "C"
+
+import (
+	"context"
+	"encoding/json"
+
+	"github.com/open-policy-agent/opa/v1/ast"
+	"github.com/open-policy-agent/opa/v1/rego"
+	regocompile "github.com/open-policy-agent/opa/v1/rego/compile"
+	"github.com/open-policy-agent/opa/v1/storage/inmem"
+)
+
+// OpaCompileFilters partially evaluates a query with respect to the given
+// unknowns and translates the residual into a data filter for the given
+// target/dialect ("sql" with postgresql/mysql/sqlserver/sqlite, or "ucast"
+// with all/prisma/linq/""). The result envelope holds
+// {"query": <string or object>, "masks": <object or null>}.
+//
+//export OpaCompileFilters
+func OpaCompileFilters(h C.ulonglong, query, inputJson, unknownsJson, target, dialect, mappingsJson, maskRule *C.char) *C.char {
+	e, err := getEngine(h)
+	if err != nil {
+		return errorJSON("invalid_handle", err.Error())
+	}
+
+	parsedQuery, err := ast.ParseBody(C.GoString(query))
+	if err != nil {
+		return errorJSON("parse_error", err.Error())
+	}
+
+	var unknownStrs []string
+	if err := json.Unmarshal([]byte(C.GoString(unknownsJson)), &unknownStrs); err != nil {
+		return errorJSON("invalid_json", err.Error())
+	}
+	unknowns := make([]*ast.Term, len(unknownStrs))
+	for i, u := range unknownStrs {
+		if unknowns[i], err = ast.ParseTerm(u); err != nil {
+			return errorJSON("parse_error", "unknown "+u+": "+err.Error())
+		}
+	}
+
+	tgt, dia := C.GoString(target), C.GoString(dialect)
+	copts := []regocompile.CompileOption{
+		regocompile.ParsedQuery(parsedQuery),
+		regocompile.ParsedUnknowns(unknowns...),
+		regocompile.Target(tgt, dia),
+	}
+
+	if s := C.GoString(mappingsJson); s != "" {
+		var mappings map[string]any
+		if err := json.Unmarshal([]byte(s), &mappings); err != nil {
+			return errorJSON("invalid_json", err.Error())
+		}
+		copts = append(copts, regocompile.Mappings(mappings))
+	}
+
+	if s := C.GoString(maskRule); s != "" {
+		ref, err := ast.ParseRef(s)
+		if err != nil {
+			return errorJSON("parse_error", "mask rule: "+err.Error())
+		}
+		copts = append(copts, regocompile.MaskRule(ref))
+	}
+
+	e.mu.Lock()
+	ropts := []func(*rego.Rego){
+		rego.Store(inmem.NewFromObject(e.data)),
+		rego.StrictBuiltinErrors(true),
+	}
+	for path, src := range e.modules {
+		ropts = append(ropts, rego.Module(path, src))
+	}
+	for _, b := range e.builtins {
+		ropts = append(ropts, makeBuiltin(uint64(h), b))
+	}
+	e.mu.Unlock()
+	copts = append(copts, regocompile.Rego(ropts...))
+
+	prepared, err := regocompile.New(copts...).Prepare(context.Background())
+	if err != nil {
+		return errorJSON("prepare_error", err.Error())
+	}
+
+	evalOpts := []rego.EvalOption{}
+	if inputJson != nil {
+		if s := C.GoString(inputJson); s != "" {
+			var input any
+			if err := json.Unmarshal([]byte(s), &input); err != nil {
+				return errorJSON("invalid_json", err.Error())
+			}
+			evalOpts = append(evalOpts, rego.EvalInput(input))
+		}
+	}
+
+	filters, err := prepared.Compile(context.Background(), evalOpts...)
+	if err != nil {
+		return errorJSON("compile_error", err.Error())
+	}
+	f := filters.For(tgt, dia)
+	return resultJSON(map[string]any{"query": f.Query, "masks": f.Masks})
+}

{opa_golib_python_bindings-0.1.2 → opa_golib_python_bindings-0.3.0}/go/go.mod

@@ -11,6 +11,9 @@ require (
 	github.com/gobwas/glob v0.2.3 // indirect
 	github.com/goccy/go-json v0.10.6 // indirect
 	github.com/google/uuid v1.6.0 // indirect
+	github.com/huandu/go-clone v1.7.3 // indirect
+	github.com/huandu/go-sqlbuilder v1.42.1 // indirect
+	github.com/huandu/xstrings v1.4.0 // indirect
 	github.com/lestrrat-go/blackmagic v1.0.4 // indirect
 	github.com/lestrrat-go/dsig v1.2.1 // indirect
 	github.com/lestrrat-go/dsig-secp256k1 v1.0.0 // indirect

{opa_golib_python_bindings-0.1.2 → opa_golib_python_bindings-0.3.0}/go/go.sum

@@ -37,6 +37,15 @@ github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/huandu/go-assert v1.1.5/go.mod h1:yOLvuqZwmcHIC5rIzrBhT7D3Q9c3GFnd0JrPVhn/06U=
+github.com/huandu/go-assert v1.1.6 h1:oaAfYxq9KNDi9qswn/6aE0EydfxSa+tWZC1KabNitYs=
+github.com/huandu/go-assert v1.1.6/go.mod h1:JuIfbmYG9ykwvuxoJ3V8TB5QP+3+ajIA54Y44TmkMxs=
+github.com/huandu/go-clone v1.7.3 h1:rtQODA+ABThEn6J5LBTppJfKmZy/FwfpMUWa8d01TTQ=
+github.com/huandu/go-clone v1.7.3/go.mod h1:ReGivhG6op3GYr+UY3lS6mxjKp7MIGTknuU5TbTVaXE=
+github.com/huandu/go-sqlbuilder v1.42.1 h1:9DVQbKg1uFNGaVqgWMpaBNkM3Fv58p2m/+AxWkTrCYc=
+github.com/huandu/go-sqlbuilder v1.42.1/go.mod h1:BEm32AHl29lzKDeV3HAIkzrz9cgRyumkDohHeGYYBoM=
+github.com/huandu/xstrings v1.4.0 h1:D17IlohoQq4UcpqD7fDk80P7l+lwAmlFaBHgOipl2FU=
+github.com/huandu/xstrings v1.4.0/go.mod h1:y5/lhBue+AyNmUVz9RLU9xbLR0o4KIIExikq4ovT0aE=
 github.com/klauspost/compress v1.19.0 h1:sXLILfc9jV2QYWkzFOPWStmcUVH2RHEB1JCdY2oVvCQ=
 github.com/klauspost/compress v1.19.0/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ=
 github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
@@ -82,6 +91,7 @@ github.com/segmentio/asm v1.2.1/go.mod h1:BqMnlJP91P8d+4ibuonYZw9mfnzI9HfxselHZr
 github.com/sirupsen/logrus v1.9.4 h1:TsZE7l11zFCLZnZ+teH4Umoq5BhEIfIzfRDZ1Uzql2w=
 github.com/sirupsen/logrus v1.9.4/go.mod h1:ftWc9WdOfJ0a92nsE2jF5u5ZwH8Bv2zdeOC42RjbV2g=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/testify v1.4.0/go.mod h1:j7eGeouHqKxXV5pUuKE4zz7dFj8WfuZ+81PSLYec5m4=
 github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
@@ -128,6 +138,7 @@ google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
+gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

opa_golib_python_bindings-0.3.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.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "opa-golib-python-bindings"
-version = "0.1.2"
+version = "0.3.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"
@@ -26,7 +26,7 @@ Repository = "https://github.com/phi1010/opa-golib-python-bindings"
 Issues = "https://github.com/phi1010/opa-golib-python-bindings/issues"
 
 [project.optional-dependencies]
-dev = ["pytest"]
+dev = ["pytest", "pyyaml"]
 
 [build-system]
 requires = ["hatchling"]

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

@@ -43,9 +43,33 @@ 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
+    ]
+
+    lib.OpaCompileFilters.restype = ctypes.c_void_p
+    lib.OpaCompileFilters.argtypes = [
+        ctypes.c_uint64,
+        ctypes.c_char_p,  # query
+        ctypes.c_char_p,  # input JSON
+        ctypes.c_char_p,  # unknowns JSON array
+        ctypes.c_char_p,  # target
+        ctypes.c_char_p,  # dialect
+        ctypes.c_char_p,  # mappings JSON
+        ctypes.c_char_p,  # mask rule ref
+    ]
 
     return lib

{opa_golib_python_bindings-0.1.2 → opa_golib_python_bindings-0.3.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,29 +186,111 @@ 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")
         return rs[0]["expressions"][0]["value"]
 
+    def compile_filters(
+        self,
+        query: str,
+        input=None,
+        *,
+        unknowns=("input",),
+        target: str = "sql",
+        dialect: str = "postgresql",
+        mappings=None,
+        mask_rule: str | None = None,
+    ):
+        """Partially evaluate ``query`` and translate it into a data filter.
+
+        Everything under the refs in ``unknowns`` (e.g. ``"input.fruits"``)
+        is left unknown; the rest is evaluated using ``input`` and the data
+        and policies already added. The residual conditions are translated
+        for ``target``/``dialect``:
+
+        - ``target="sql"`` with dialect ``postgresql``, ``mysql``,
+          ``sqlserver`` or ``sqlite``: returns a SQL WHERE clause string.
+        - ``target="ucast"`` with dialect ``all``, ``prisma``, ``linq`` or
+          ``""``: returns a UCAST condition object (JSON-compatible dict).
+
+        ``mappings`` optionally renames tables/columns (see the OPA docs on
+        Compile API mappings); ``mask_rule`` names a rule (e.g.
+        ``"data.filters.masks"``) evaluated to produce column masks.
+
+        Returns ``{"query": <str or dict or None>, "masks": <dict or None>}``.
+        A query of ``None`` means the policy can never be satisfied; an empty
+        query means it is always satisfied. Raises OpaError with code
+        ``compile_error`` if the residual policy cannot be expressed as a
+        filter for the chosen target.
+
+        Unknown refs are limited to ``input.<table>.<column>`` — exactly two
+        segments after ``input``, for every target/dialect, wherever the
+        declared unknown boundary sits (``mappings`` cannot deepen this):
+        ``unknowns=["input.item"]`` permits only ``input.item.<column>``,
+        the bare ``unknowns=["input"]`` permits ``input.<table>.<column>``.
+        Nested documents like ``input.item.attrs.price.value`` are rejected
+        and must be flattened into columns; a dynamic column picked from
+        known values (``input.attr[sprintf("value_%s", [input.locale])]``)
+        is fine, as it resolves during partial evaluation.
+        """
+        self._check_open()
+        envelope = self._call(
+            self._lib.OpaCompileFilters,
+            query.encode(),
+            _encode_input(input),
+            json.dumps(list(unknowns)).encode(),
+            target.encode(),
+            dialect.encode(),
+            b"" if mappings is None else json.dumps(mappings).encode(),
+            (mask_rule or "").encode(),
+        )
+        return envelope.get("result")
+
 
 def _encode_input(input):
     if input is None:

opa_golib_python_bindings-0.1.2/PKG-INFO

@@ -1,73 +0,0 @@
-Metadata-Version: 2.5
-Name: opa-golib-python-bindings
-Version: 0.1.2
-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
-Project-URL: Issues, https://github.com/phi1010/opa-golib-python-bindings/issues
-Author: Phillip Kuhrt
-License-Expression: Apache-2.0
-License-File: LICENSE
-Keywords: authorization,opa,open-policy-agent,policy,rego
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: Operating System :: MacOS
-Classifier: Operating System :: POSIX :: Linux
-Classifier: Programming Language :: Go
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Topic :: Security
-Classifier: Topic :: Software Development :: Libraries
-Requires-Python: >=3.14
-Provides-Extra: dev
-Requires-Dist: pytest; extra == 'dev'
-Description-Content-Type: text/markdown
-
-# opa-golib-python-bindings
-
-Python bindings for the [OPA](https://www.openpolicyagent.org/) Rego engine, embedding
-`github.com/open-policy-agent/opa/v1/rego` via a Go c-shared library and a stdlib-only
-ctypes wrapper.
-
-## Build
-
-Requires Go >= 1.26 and Python >= 3.14.
-
-```sh
-make build   # builds src/opa_bindings/libopabridge.so
-make test    # builds + runs pytest
-```
-
-## Usage
-
-```python
-from opa_bindings import OpaEngine
-
-users = {"alice": {"role": "admin"}}
-
-with OpaEngine() as engine:
-    engine.add_policy("authz.rego", """
-package authz
-
-allow if lookup_user(input.user).role == "admin"
-""")
-    engine.add_data({"admin": ["alice"]}, path="roles")   # deep-merged; conflicts raise
-    engine.register_function("lookup_user", lambda name: users.get(name))
-
-    engine.eval_document("authz.allow", {"user": "alice"})  # -> True
-    engine.eval_query("x = data.roles.admin[_]")            # -> [{"x": "alice"}]
-```
-
-Notes:
-
-- `add_data` deep-merges objects; identical values coexist, conflicting values raise
-  `OpaError(code="merge_conflict")` naming the conflicting path.
-- `register_function` infers arity from the callable's signature. A `*args` function is
-  variadic and is called from Rego with a single array argument: `many(["a", "b"])`
-  (OPA does not support variadic builtins with return values).
-- Builtin arguments and return values are JSON-compatible objects. A callback exception
-  becomes an evaluation error; returning is fine.
-- An undefined document raises `OpaUndefinedError`.
-- 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/README.md

@@ -1,48 +0,0 @@
-# opa-golib-python-bindings
-
-Python bindings for the [OPA](https://www.openpolicyagent.org/) Rego engine, embedding
-`github.com/open-policy-agent/opa/v1/rego` via a Go c-shared library and a stdlib-only
-ctypes wrapper.
-
-## Build
-
-Requires Go >= 1.26 and Python >= 3.14.
-
-```sh
-make build   # builds src/opa_bindings/libopabridge.so
-make test    # builds + runs pytest
-```
-
-## Usage
-
-```python
-from opa_bindings import OpaEngine
-
-users = {"alice": {"role": "admin"}}
-
-with OpaEngine() as engine:
-    engine.add_policy("authz.rego", """
-package authz
-
-allow if lookup_user(input.user).role == "admin"
-""")
-    engine.add_data({"admin": ["alice"]}, path="roles")   # deep-merged; conflicts raise
-    engine.register_function("lookup_user", lambda name: users.get(name))
-
-    engine.eval_document("authz.allow", {"user": "alice"})  # -> True
-    engine.eval_query("x = data.roles.admin[_]")            # -> [{"x": "alice"}]
-```
-
-Notes:
-
-- `add_data` deep-merges objects; identical values coexist, conflicting values raise
-  `OpaError(code="merge_conflict")` naming the conflicting path.
-- `register_function` infers arity from the callable's signature. A `*args` function is
-  variadic and is called from Rego with a single array argument: `many(["a", "b"])`
-  (OPA does not support variadic builtins with return values).
-- Builtin arguments and return values are JSON-compatible objects. A callback exception
-  becomes an evaluation error; returning is fine.
-- An undefined document raises `OpaUndefinedError`.
-- 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.