or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

enum-system.mdfield-system.mdindex.mdmarshal-system.mdmessage-system.mdmodule-system.md
tile.json

tessl/pypi-proto-plus

Beautiful, Pythonic protocol buffers that make protocol buffer message classes behave like native Python types

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/proto-plus@1.26.x

To install, run

npx @tessl/cli install tessl/pypi-proto-plus@1.26.0

index.mddocs/

Proto Plus

Beautiful, Pythonic protocol buffers that make protocol buffer message classes behave like native Python types. This library provides a wrapper around Google's protobuf library that makes working with protocol buffers more intuitive and idiomatic in Python, enabling seamless integration with Python's type system and standard library.

Package Information

  • Package Name: proto-plus
  • Language: Python
  • Installation: pip install proto-plus

Core Imports

import proto

For common usage patterns:

from proto import Message, Field, Enum, RepeatedField, MapField

Type constants can be imported directly:

from proto import STRING, INT32, BOOL, MESSAGE, ENUM

Basic Usage

import proto

# Define an enum
class Color(proto.Enum):
    RED = 1
    GREEN = 2
    BLUE = 3

# Define a message
class Person(proto.Message):
    name = proto.Field(proto.STRING, number=1)
    age = proto.Field(proto.INT32, number=2)
    email = proto.Field(proto.STRING, number=3, optional=True)
    favorite_color = proto.Field(Color, number=4)
    hobbies = proto.RepeatedField(proto.STRING, number=5)

# Create and use messages
person = Person(
    name="Alice",
    age=30,
    email="alice@example.com",
    favorite_color=Color.BLUE,
    hobbies=["reading", "hiking"]
)

# Access fields like native Python attributes
print(person.name)  # "Alice"
print(person.age)   # 30

# Convert to/from JSON
json_str = Person.to_json(person)
person_from_json = Person.from_json(json_str)

# Convert to/from dict
person_dict = Person.to_dict(person)
person_from_dict = Person(person_dict)

# Serialize/deserialize
serialized = Person.serialize(person)
deserialized = Person.deserialize(serialized)

Architecture

Proto-plus uses Python metaclasses to automatically generate protocol buffer descriptors and create seamless integration between protobuf messages and Python objects:

  • Message metaclass: Automatically generates protobuf descriptors and provides Pythonic behavior
  • Field system: Defines message structure with automatic type conversion and validation
  • Marshal system: Handles conversion between protobuf and Python native types
  • Module system: Manages package organization and protocol buffer file generation

This design enables protocol buffer messages to behave like native Python classes while maintaining full compatibility with the underlying protobuf library and wire format.

Capabilities

Message Definition and Usage

Core functionality for defining protocol buffer messages that behave like Python classes, with automatic serialization, deserialization, and type conversion.

class Message(metaclass=MessageMeta):
    def __init__(self, mapping=None, *, ignore_unknown_fields=False, **kwargs): ...
    
    @classmethod
    def pb(cls, obj=None, *, coerce: bool = False): ...
    
    @classmethod
    def wrap(cls, pb): ...
    
    @classmethod  
    def serialize(cls, instance) -> bytes: ...
    
    @classmethod
    def deserialize(cls, payload: bytes) -> "Message": ...
    
    @classmethod
    def to_json(cls, instance, **kwargs) -> str: ...
    
    @classmethod
    def from_json(cls, payload, *, ignore_unknown_fields=False) -> "Message": ...
    
    @classmethod
    def to_dict(cls, instance, **kwargs) -> dict: ...
    
    @classmethod
    def copy_from(cls, instance, other): ...

Message System

Field Definition

Field types for defining message structure, supporting all protocol buffer field types including primitives, messages, enums, repeated fields, and maps.

class Field:
    def __init__(self, proto_type, *, number: int, message=None, enum=None, 
                 oneof: str = None, json_name: str = None, optional: bool = False): ...

class RepeatedField(Field): ...

class MapField(Field):
    def __init__(self, key_type, value_type, *, number: int, message=None, enum=None): ...

Field System

Enum Definition

Protocol buffer enums that behave like Python enums with integer compatibility and full comparison support.

class Enum(enum.IntEnum, metaclass=ProtoEnumMeta): ...

Enum System

Type Marshaling

Advanced type conversion system for seamless integration between protocol buffers and Python native types, including support for well-known types.

class Marshal:
    def __init__(self, *, name: str): ...
    def register(self, proto_type: type, rule: Rule = None): ...
    def to_python(self, proto_type, value, *, absent: bool = None): ...
    def to_proto(self, proto_type, value, *, strict: bool = False): ...
    def reset(self): ...

Marshal System

Module Organization

Package and module management utilities for organizing protocol buffer definitions across multiple files and packages.

def define_module(*, package: str, marshal: str = None, 
                  manifest: Set[str] = frozenset()) -> _ProtoModule: ...

Module System

Protocol Buffer Types

class ProtoType(enum.IntEnum):
    DOUBLE = 1
    FLOAT = 2
    INT64 = 3
    UINT64 = 4
    INT32 = 5
    FIXED64 = 6
    FIXED32 = 7
    BOOL = 8
    STRING = 9
    MESSAGE = 11
    BYTES = 12
    UINT32 = 13
    ENUM = 14
    SFIXED32 = 15
    SFIXED64 = 16
    SINT32 = 17
    SINT64 = 18

All ProtoType values are available as module-level constants: DOUBLE, FLOAT, INT64, UINT64, INT32, FIXED64, FIXED32, BOOL, STRING, MESSAGE, BYTES, UINT32, ENUM, SFIXED32, SFIXED64, SINT32, SINT64