Wren Core Python Binding
Python bindings for wren-core, the Rust semantic engine behind Wren Engine. Built with PyO3 and Maturin.
Wren Engine translates SQL queries through a semantic layer (MDL - Modeling Definition Language) and executes them against 22+ data sources (PostgreSQL, BigQuery, Snowflake, etc.).
Installation
pip install wren-core-py
Requires Python >= 3.11.
Pre-built wheels are available for:
- Linux x86_64 / ARM64 (manylinux)
- macOS x86_64 / ARM64 (Apple Silicon)
- Windows x86_64
On any other platform pip falls back to the sdist and builds from source, which requires a Rust toolchain.
Quick Start
from wren_core import SessionContext
# Create a session context from a base64-encoded MDL JSON string
base64_mdl_json = "<your-base64-encoded-mdl-json>"
ctx = SessionContext(base64_mdl_json)
# Transform a SQL query through the semantic layer
planned_sql = ctx.transform_sql("SELECT * FROM my_model")
Registering local files (Parquet/CSV)
Physical files can back MDL models via two-phase initialization — register the files, then load the MDL so models resolve to them:
from wren_core import SessionContext
base64_mdl_json = "<your-base64-encoded-mdl-json>"
ctx = SessionContext()
ctx.register_parquet("customer", "/data/customer.parquet")
ctx.register_csv("orders", "/data/orders.csv")
ctx.load_mdl(base64_mdl_json) # MDL models now resolve to the files
# Query by the MDL's catalog.schema.model name; returns Arrow IPC stream bytes
ipc_bytes = ctx.query("SELECT * FROM my_catalog.my_schema.customer")
Visibility contract:
- Tables land in the pre-existing default catalog (
datafusion.public). An MDL model resolves to a registered file only if itstableReferenceis{"catalog": "datafusion", "schema": "public", "table": "<registered name>"}and the columns it declares exist in the file. - Registering after the context was created still works: the internals of
pre-existing catalogs are live-shared with derived contexts, so the table is
visible to
query,dry_run, andlist_tables. - Brand-new top-level catalogs are the exception — they must exist before
MDL construction,
load_mdl, or a transform, each of which snapshots the top-level catalog list. - For
load_mdl's overlap rule, see the Concurrency section below.
For complete runnable examples (fixture files, matching manifests, decoding
the returned bytes), see tests/test_physical_tables.py.
Concurrency
Calls on one SessionContext run in parallel. Each transform_sql works
on a private top-level catalog snapshot and analyzer state is
per-invocation, so supported concurrent calls never observe each other's
intermediate state. The contract:
- Concurrent execution is supported for the read-only inputs accepted by
transform_sqlandquery, and for the registration APIs.dry_runis concurrency-safe for statements thatEXPLAINonly plans. AnANALYZE-prefixed input becomesEXPLAIN ANALYZEand executes; like a state-mutating statement accepted byquery(), it is outside the concurrency contract. Function lookup methods are read-only and concurrency-safe. register_parquet/register_csvare safe under distinct table names; registering the same name concurrently is unsupported.list_tablesis a best-effort enumeration: registrations that land mid-call may or may not appear, but the result is always well-formed.load_mdlmust not overlap other calls on the same context; overlapping calls raiseRuntimeError.
Developer Guide
Environment Setup
- Install Rust and Cargo
- Install Python
- Install uv
- Install casey/just
Test and Build
After installing casey/just, you can use the following commands:
just install— Create Python venv and install dependencies.just develop— Build the Rust package for local development (required before running Python tests).just test-rs— Run Rust tests only.just test-py— Run Python tests only.just test— Run both Rust and Python tests.just build— Build the Python wheel. Output goes totarget/wheels/.
Coding Style
Format via just format.
Publishing
See scripts/publish.sh for local publishing to PyPI/TestPyPI:
./scripts/publish.sh --build # Build wheel only
./scripts/publish.sh --test # Build + publish to TestPyPI
./scripts/publish.sh # Build + publish to PyPI
License
Apache-2.0
Metadata
Release files for wren-core-py 0.8.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| wren_core_py-0.8.2.tar.gz | 236.3 kB | Without provenance | Details for wren_core_py-0.8.2.tar.gz |
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| wren_core_py-0.8.2-cp311-abi3-win_amd64.whl | CPython 3.11 | abi3 | Windows x86-64 | Details for wren_core_py-0.8.2-cp311-abi3-win_amd64.whl |
| wren_core_py-0.8.2-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl | CPython 3.11 | abi3 | Linux glibc 2.17+ x86-64 | Details for wren_core_py-0.8.2-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
| wren_core_py-0.8.2-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl | CPython 3.11 | abi3 | Linux glibc 2.17+ ARM64 | Details for wren_core_py-0.8.2-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
| wren_core_py-0.8.2-cp311-abi3-macosx_11_0_arm64.whl | CPython 3.11 | abi3 | macOS 11.0+ ARM64 | Details for wren_core_py-0.8.2-cp311-abi3-macosx_11_0_arm64.whl |
| wren_core_py-0.8.2-cp311-abi3-macosx_10_12_x86_64.whl | CPython 3.11 | abi3 | macOS 10.12+ x86-64 | Details for wren_core_py-0.8.2-cp311-abi3-macosx_10_12_x86_64.whl |
Total release size: 246.7 MB
Release files / wren_core_py-0.8.2.tar.gz
| Download URL | wren_core_py-0.8.2.tar.gz |
|---|---|
| Size | 236.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c2711dc74c0de37ffd7777735830e737102e7e99bebb13aebc5d3f05a575c52b
|
|
BLAKE2b-256 checksum How to use checksums |
cf573abf7dfc2104871c7a31dba14cbc355ab96cc63e36dbc7eadd2ecc267c12
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / wren_core_py-0.8.2-cp311-abi3-win_amd64.whl
| Download URL | wren_core_py-0.8.2-cp311-abi3-win_amd64.whl |
|---|---|
| Size | 46.1 MB |
| Tags | CPython 3.11 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
38e015e9ea33b1daaeb32838edab10f6cf31cc83b1fd9b4833ff87f41f731549
|
|
BLAKE2b-256 checksum How to use checksums |
55bde33fc2551ce10eeeff76392126e181c7ca89542a459eba9ee0be38c2a3a5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / wren_core_py-0.8.2-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | wren_core_py-0.8.2-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 51.8 MB |
| Tags | CPython 3.11 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
54cf19fb9a646e4ef3700781a2177a9d09284684202a8dca2aea0e0fcc3cf553
|
|
BLAKE2b-256 checksum How to use checksums |
f82b7e9d7c67877bc26ebc73512ab915f449da08d6f2f6c00bcbaf548d42ced5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / wren_core_py-0.8.2-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | wren_core_py-0.8.2-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 53.6 MB |
| Tags | CPython 3.11 Linux glibc 2.17+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
c8bd81272198a574e7127eb062d7097ab42286e97ae166d749524714dbc630a9
|
|
BLAKE2b-256 checksum How to use checksums |
baf072fffbf69a4c7d966d7ff82ca7875b8787112a4f46b6c9a132171b44386b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / wren_core_py-0.8.2-cp311-abi3-macosx_11_0_arm64.whl
| Download URL | wren_core_py-0.8.2-cp311-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 46.5 MB |
| Tags | CPython 3.11 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
809a1eca6e10fe748a4bb24f81f9f8e11099c2e96344587fdea44455bc616a1a
|
|
BLAKE2b-256 checksum How to use checksums |
d15e1687da51d5adbb70ce169d83b31038b10c659b1806f4e0097d51124d3c27
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / wren_core_py-0.8.2-cp311-abi3-macosx_10_12_x86_64.whl
| Download URL | wren_core_py-0.8.2-cp311-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 48.4 MB |
| Tags | CPython 3.11 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
9af21b41fa54b6f787b5a3ca772a6e124cefd2b9028712512a12bdae8c5991ef
|
|
BLAKE2b-256 checksum How to use checksums |
ca5e8081f4eb3893f5474f2f3fd081b4822926392991b0013b3eade0e5ac18bb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Security for wren-core-py 0.8.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.