up-py-rs

Python bindings for the Eclipse uProtocol Rust implementation (up-rust). This package provides high-performance Python APIs for uProtocol communication patterns by leveraging Rust's speed and safety.

Features

• 🚀 High Performance: Rust-powered implementations with minimal Python overhead
• 🔒 Type Safe: Full type hints and stub files for excellent IDE support
• 📡 Complete uProtocol Support: Publishers, Notifiers, and Transport implementations
• 🐍 Pythonic API: Easy-to-use interfaces that feel natural in Python
• ⚡ Async Ready: Built on Tokio async runtime for efficient I/O operations

Installation

Install from PyPI:

# Basic installation (includes LocalTransport and core features)
pip install up-py-rs

# Build from source with specific transports:
pip install up-py-rs[zenoh]  # Note: Requires build tools (see below)
pip install up-py-rs[all]    # All features

Important: The PyPI wheel includes only the base features. For transport protocols like Zenoh, you need to either:

1. Build from source (recommended for transport features):

   pip install maturin
   pip install up-py-rs --no-binary up-py-rs --config-settings="--features=zenoh"
   

2. Install the pre-built complete wheel (if available for your platform):

   pip install up-py-rs-complete  # Includes all transports
   

3. Use a Docker image with pre-built binaries (coming soon)

Or using uv:

uv add up-py-rs
# Build with features
uv pip install up-py-rs --no-binary up-py-rs

Optional Dependencies

up-py-rs supports modular installation through build-time features:

Development Installation (includes all features):

git clone https://github.com/sachinkum0009/up-py-rs.git
cd up-py-rs
pip install maturin
maturin develop --features all-transports

Quick Start

Simple Publisher (Local Transport)

For in-process communication without network overhead:

from up_py_rs import StaticUriProvider
from up_py_rs.local_transport import LocalTransport
from up_py_rs.communication import SimplePublisher, UPayload

# Setup
uri_provider = StaticUriProvider("my-vehicle", 0xa34b, 0x01)
transport = LocalTransport()
publisher = SimplePublisher(transport, uri_provider)

# Publish a message
payload = UPayload.from_string("Hello from Python!")
publisher.publish(0xb4c1, payload)

Zenoh Publisher (Network Transport)

For distributed communication across network boundaries:

from up_py_rs import StaticUriProvider
from up_py_rs.zenoh_transport import UPTransportZenoh
from up_py_rs.communication import SimplePublisher, UPayload

# Setup Zenoh transport
uri_provider = StaticUriProvider("publisher", 0x3b1da, 1)
transport = UPTransportZenoh.builder("publisher").build()
publisher = SimplePublisher(transport, uri_provider)

# Publish messages
for i in range(1, 11):
    payload = UPayload.from_string(f"event {i}")
    publisher.publish(0x8001, payload)

Note: Requires pip install up-py-rs[zenoh]

Simple Notifier

from up_py_rs import StaticUriProvider
from up_py_rs.local_transport import LocalTransport
from up_py_rs.communication import SimpleNotifier, UPayload

def notification_handler(msg):
    text = msg.extract_string()
    if text:
        print(f"Received: {text}")

# Setup
uri_provider = StaticUriProvider("my-vehicle", 0xa34b, 0x01)
transport = LocalTransport()
notifier = SimpleNotifier(transport, uri_provider)

# Register listener
topic = uri_provider.get_resource_uri(0xd100)
notifier.start_listening(topic, notification_handler)

# Send notification
payload = UPayload.from_string("Alert!")
destination = uri_provider.get_source_uri()
notifier.notify(0xd100, destination, payload)

# Cleanup
notifier.stop_listening(topic, notification_handler)

Components

LocalTransport

In-process message transport for testing and local communication without network overhead. Best for single-process applications and testing.

UPTransportZenoh

Zenoh-based network transport for distributed communication across network boundaries. Enables pub/sub patterns between different processes, devices, or vehicles. Requires zenoh extra.

StaticUriProvider

Creates and manages uProtocol URIs for identifying entities in the network.

SimplePublisher

High-level API for publishing messages to specific resources. Works with any transport (Local or Zenoh).

SimpleNotifier

Send and receive notifications between uEntities with listener callbacks.

UPayload

Message payload wrapper supporting strings and raw bytes with protobuf format.

Development

Building from Source

Requirements:

• Python 3.8+
• Rust toolchain (for building)
• uv or pip

# Clone the repository
git clone https://github.com/sachinkum0009/up-py-rs.git
cd up-py-rs

# Build in development mode
uv run maturin develop

# Run tests
uv run pytest

# Run examples
uv run python examples/simple_publish.py
uv run python examples/simple_notify.py

# Run Zenoh examples (requires zenoh extra)
uv add up-py-rs --extra zenoh

# Terminal 1: Start subscriber
uv run python examples/simple_zenoh_subscriber.py

# Terminal 2: Start publisher
uv run python examples/simple_zenoh_publisher.py

Building Wheels

# Build release wheel
uv run maturin build --release

# Build and publish to PyPI
uv run maturin publish

Architecture

up-py-rs bridges Python and Rust using PyO3:

• Rust Core: High-performance implementations from up-rust
• PyO3 Bindings: Zero-cost abstractions between Python and Rust
• Python API: Pythonic interfaces with full type hints

Each async operation maintains its own Tokio runtime for thread-safe execution across the Python/Rust boundary.

Contributing

Contributions are welcome! Please see the contribution guidelines for details.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Links

• Eclipse uProtocol Specification
• up-rust (Rust Implementation)
• PyO3 Documentation
• Issue Tracker

Acknowledgments

Built with:

• Eclipse uProtocol - The underlying protocol specification
• PyO3 - Rust bindings for Python
• Maturin - Build tool for Rust/Python projects