opa-py-wasm

opa-py-wasm is an in-process, thread-safe Python SDK for evaluating Open Policy Agent policies compiled to WebAssembly, built on wasmtime.py. It requires no OPA server, no OPA binary, no subprocess, and no network at runtime. It is functionally comparable to StyraOSS opa-java-wasm, with a Pythonic API and explicit thread-safety guarantees.

Import name: the package installs as opa-py-wasm and is imported as opapywasm.

Installation

pip install opa-py-wasm

Or with uv:

uv add opa-py-wasm

Requires Python 3.10 or newer. The only runtime dependency is wasmtime.

Usage

from opapywasm import UNDEFINED, OpaWasmPolicy, PolicyConfig

policy = OpaWasmPolicy.from_wasm_file(
    "policy.wasm",
    config=PolicyConfig(
        pool_size=8,
        default_entrypoint="authz/allow",
        eval_timeout_seconds=30.0,   # per-eval deadline (epoch interruption)
        max_memory_pages=4096,       # per-instance linear-memory cap (256 MiB)
    ),
)

policy.set_data({"roles": {"alice": "admin", "bob": "viewer"}})

decision = policy.evaluate({"user": "alice", "action": "delete"})   # simplified decision
raw = policy.evaluate_raw({"user": "alice", "action": "delete"})    # full OPA result set

# `evaluate` distinguishes an undefined decision from a defined JSON null:
if decision is UNDEFINED:
    ...          # policy produced no result
elif decision is None:
    ...          # policy result was JSON null

# Custom host builtins (receive decoded Python args, return JSON-compatible values):
policy.register_builtin("my.custom", lambda x: {"ok": True})

OpaWasmPolicy is a bounded, thread-safe pool — construct it once and call evaluate from many threads. Runnable scripts are in examples/: basic_authz.py, pooled_eval.py, custom_builtin.py, yaml_builtin.py.

For the YAML default builtins, install the optional extra:

uv add "opa-py-wasm[yaml]"

Start with the user guide — an end-to-end walkthrough covering compiling a policy, result semantics, concurrency, data updates, memory behaviour, host builtins, and a production adoption checklist.

See docs/ for the focused references: architecture, thread-safety, the OPA Wasm ABI, the opa-java-wasm parity table, and capacity-planning guidance for sizing pool size and concurrency.

Test fixtures (dev only)

Compiled .wasm fixtures are committed under tests/fixtures/wasm, so the test suite needs no OPA CLI. To regenerate them from the Rego sources in tests/fixtures/rego, install the OPA CLI and run:

python scripts/build_fixtures.py           # all fixtures
python scripts/build_fixtures.py allow_true # a single fixture

Local Development

uv

This library uses uv to manage Python dependencies.
brew is The easiest way to install on macOS:

brew install uv

For additional installation options (e.g. setting the PATH, installing a specific version, etc), see the installation docs:
https://docs.astral.sh/uv/getting-started/installation/

Python Versions Supported

Python 3.10 through 3.14 are supported and tested in CI.

To change which versions are supported and tested:

• Update "envlist" in "tox" section of tox.ini
• Update "Supported Python versions" badge in README.md
• Update "project.requires-python" in pyproject.toml (if needed)
• Update "tool.black.target-version" in pyproject.toml (optional)
• Update the matrix in .github/workflows/ci.yml

Virtual Environment

Create by running:

uv sync --all-extras

Run a command from the virtual environment, like code formatting:

uv run black .

To activate the virtual environment:

source .venv/bin/activate

For more information, refer to uv's documentation.

Type checking (mypy)

This library supports Python type annotation. Types will be checked as part of the test suite (see below). For more information, see the mypy documentation.

Testing

To run the test suite locally:

uv run tox

Coverage is enforced on every CI run by fail_under = 90 in tool.coverage.report; the suite currently sits at 99%. The coverage badge at the top of this file is static — if you change coverage materially, update the percentage in that badge along with your change.

Releasing

Releases are cut by maintainers by pushing a vX.Y.Z tag, which triggers an automated build and publish to PyPI. See RELEASING.md for the process and the versioning policy. Published versions are listed on PyPI, and each release's changes are in CHANGELOG.md.

Contributing

Contributions are welcome — see the Contribution Guidelines and our Code of Conduct.

Support

Please open a GitHub issue for bugs and feature requests, or start a discussion for questions.

License

Released under the MIT License.