Skip to content

protoruf

High-performance JSON ↔ Protobuf conversion for Python, powered by Rust

CI Status PyPI Version License Python Version

Overview

protoruf is a Python library written in Rust that provides blazing-fast conversion between JSON and Protobuf messages. Built on top of prost-reflect and protox, it offers type-safe serialization with explicit message type specification.

Why protoruf?

  • ⚡ Blazing Fast — Core logic implemented in Rust for maximum performance
  • 🔒 Type-Safe — Explicit message types prevent serialization errors
  • 📦 Zero External Dependencies — Built-in proto compilation with Rust protox
  • 🎯 Complete Protobuf Support — Nested messages, enums, repeated fields, maps, oneof
  • 🐍 Pythonic API — Clean, intuitive interface with full type hints

Quick Example

from protoruf import compile_proto, json_to_protobuf, protobuf_to_json

# Compile your .proto file
descriptor = compile_proto("message.proto")

# Convert JSON to Protobuf
json_data = '{"id": "123", "content": "Hello", "priority": 1}'
protobuf_bytes = json_to_protobuf(json_data, descriptor, message_type="message.Message")

# Convert Protobuf back to JSON
result = protobuf_to_json(protobuf_bytes, descriptor, message_type="message.Message", pretty=True)
print(result)

Getting Started

  • Installation

    Install protoruf via pip and verify your setup

    Get Started →

  • Quick Start

    Build your first proto message in 5 minutes

    Quick Start →

  • User Guide

    Learn basic usage, proto files, and advanced features

    Read Guide →

  • API Reference

    Complete API documentation with examples

    View API →

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Python Application                      │
│              compile_proto()  │  json_to_protobuf()         │
│              protobuf_to_json()  │  load_descriptor()       │
│      pydantic_to_protobuf()  │  protobuf_to_pydantic()      │
├─────────────────────────────────────────────────────────────┤
│                   PyO3 Rust Bindings                        │
├─────────────────────────────────────────────────────────────┤
│         protox  │  prost-reflect  │  serde_json             │
└─────────────────────────────────────────────────────────────┘

Features

Feature Description
JSON ↔ Protobuf Bidirectional conversion with full type safety
Proto Compilation Compile .proto files without external tools
Nested Messages Full support for nested message types
Enums Automatic string ↔ number conversion
Repeated Fields Handle lists and arrays seamlessly
Maps Convert dictionary structures
Oneof Fields Support for union types
Pydantic Integration Direct conversion with pydantic_to_protobuf() and protobuf_to_pydantic()

Next Steps