Skip to main content

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 its tableReference is {"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, and list_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_sql and query, and for the registration APIs. dry_run is concurrency-safe for statements that EXPLAIN only plans. An ANALYZE-prefixed input becomes EXPLAIN ANALYZE and executes; like a state-mutating statement accepted by query(), it is outside the concurrency contract. Function lookup methods are read-only and concurrency-safe.
  • register_parquet / register_csv are safe under distinct table names; registering the same name concurrently is unsupported.
  • list_tables is a best-effort enumeration: registrations that land mid-call may or may not appear, but the result is always well-formed.
  • load_mdl must not overlap other calls on the same context; overlapping calls raise RuntimeError.

Developer Guide

Environment Setup

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 to target/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)

Source distribution for wren-core-py 0.8.2
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)

Table of built distributions (wheels) for wren-core-py 0.8.2
File Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page