Python Bindings

Loading…

Python Bindings

Relevant source files

• experiments/bindings/python-ws-client/Cargo.lock
• experiments/bindings/python_(old_client)/pyproject.toml/pyproject.toml)

This section provides an overview of the Python integration strategies for SIMD R Drive. The project offers two distinct approaches for interacting with the storage engine from Python: a high-performance WebSocket-based client for networked environments and a legacy direct binding for local embedded use cases. Both implementations utilize PyO3 and maturin to bridge Rust performance with Python ergonomics.

Binding Architecture Overview

The following diagram illustrates how the Python bindings interface with the core Rust components, bridging the gap between Python user-space and the underlying Rust storage logic.

Python Binding System Context

graph TD
    subgraph "Python_User_Space"
        [simd_r_drive_ws_client] --> [DataStoreWsClient_Python]
        [simd-r-drive-py] --> [DataStore_Python]
    end

    subgraph "Rust_Binding_Layer_PyO3"
        [DataStoreWsClient_Python] -- "wraps" --> [WsClient_Rust]
        [DataStore_Python] -- "wraps" --> [DataStore_Rust]
    end

    subgraph "Rust_Backend_Crates"
        [WsClient_Rust] -- "RPC_via_muxio" --> [simd-r-drive-ws-server]
        [simd-r-drive-ws-server] -- "calls" --> [DataStore_Rust]
        [DataStore_Rust] -- "io" --> [Disk_Storage]
    end

Sources: experiments/bindings/python_(old_client)/pyproject.toml1-4 experiments/bindings/python-ws-client/Cargo.lock:133-143

Python WebSocket Client Binding

The simd_r_drive_ws_client is the primary, modern binding. It acts as a thin PyO3 wrapper around the Rust WsClient, enabling Python applications to communicate with a simd-r-drive-ws-server instance over WebSockets.

• API Surface : Exposes the DataStoreWsClient class, which provides asynchronous access to the storage engine. It supports standard operations like write, read, and Pythonic metadata checks such as __contains__ and __len__.
• Tooling : The development environment uses uv for dependency management and virtual environment isolation.
• Testing : Includes an automated lifecycle script, integration_test.sh, which manages the end-to-end flow: spinning up a simd-r-drive-ws-server, building the Python wheel, and running pytest. It also features a unique extract_readme_tests.py script that converts documentation examples into executable test cases.

For details, see Python WebSocket Client Binding.

Sources: experiments/bindings/python-ws-client/Cargo.lock:133-143 experiments/bindings/python-ws-client/Cargo.lock1633

Python Direct Binding (Legacy)

The simd-r-drive-py package is a legacy implementation that binds directly to the DataStore core library. It allows Python to load the storage engine as a shared library without requiring a separate server process.

• Platform Support : Targets CPython 3.10 through 3.13 on Linux and macOS experiments/bindings/python_(old_client)/pyproject.toml20-25
• Status : This binding is considered experimental/alpha experiments/bindings/python_(old_client)/pyproject.toml3-11
• Build System : Configured via pyproject.toml using the maturin build backend experiments/bindings/python_(old_client)/pyproject.toml28-30

For details, see Python Direct Binding (Legacy)).

Sources: experiments/bindings/python_(old_client)/pyproject.toml1-34

Comparison of Approaches

Binding Logic Flow

Sources: experiments/bindings/python_(old_client)/pyproject.toml32-34 experiments/bindings/python-ws-client/Cargo.lock1633