Python-Rust Bridge Example

This repository demonstrates the Python-Rust bridge pattern through a practical text processing pipeline example. It shows how to combine Rust's performance with Python's flexibility using PyO3 for safe language interop.

Overview

The example implements a text processor that:

• Processes text efficiently in Rust (core operations)
• Executes Python plugins from within Rust (extensibility)
• Handles errors safely across the language boundary

This pattern is used by production libraries like Polars, Ruff, and others to deliver both performance and extensibility.

Architecture

Python API (User-facing) → PyO3 Boundary → Rust Core (Performance)

• Rust Core (rust-core/): Performance-critical text processing and plugin management
• Boundary Layer (boundary/): PyO3 bindings that expose Rust to Python
• Python Package (python/): User-facing API and plugin system

Quick Start

1. Setup environment:

   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate

2. Build and install:

   cd python
   maturin develop
   cd ..

3. Run the example:

   python example.py

Expected Output

The example processes text through Rust (trimming whitespace) then applies Python plugins (reverse, capitalize):

Original text:
'\n    hello world\n    this is a test\n    of our processor\n    '

Final output:

Dlrow olleh
Tset a si siht
Rossecorp ruo fo

Key Concepts Demonstrated

• Plugin Management: Loading and executing Python code from Rust
• Memory Efficiency: Data stays in Rust's memory space throughout processing
• Error Handling: Safe conversion between Rust errors and Python exceptions
• Build Configuration: Workspace setup for mixed-language projects

Learn More

This example accompanies the comprehensive blog post:

Building Python-Rust Applications: A Complete Guide

The blog post covers:

• When to use this pattern vs alternatives
• Real-world case studies (Polars, Ruff, Angreal)
• Detailed implementation walkthrough
• Production deployment considerations
• Common pitfalls and best practices

Requirements

• Python 3.8+
• Rust 1.70+
• uv or virtualenv
• maturin (installed automatically)