Registry / serialization / protobuf-to-pydantic

protobuf-to-pydantic

JSON →
library0.3.3.1pypypi✓ verified 87d ago

protobuf-to-pydantic is a Python library that generates `pydantic.BaseModel` classes with parameter verification functions directly from Protobuf files (proto3 syntax). It supports both runtime object generation and plugin-based code generation, enabling robust data validation for Protobuf messages within Python applications. The library is actively maintained with frequent minor releases, currently at version 0.3.3.1.

pip install protobuf-to-pydantic
INSTALL
IMPORT
SIG · PROTOBUF-TO-PYDANT
P
protobuf-to-pydantic
serializationpythonv0.3.3.1
Install
3.8s avg
Import
706ms
Disk
31MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.3.3.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.940 runs
installs and imports cleanly · install 0.0s · import 0.841s · 32.4MB
glibc
py 3.103.940 runs
installs and imports cleanly · install 3.8s · import 0.571s · 32MB
31MB installed
● package 31MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

msg_to_pydantic_model
from protobuf_to_pydantic import msg_to_pydantic_model
Template
from protobuf_to_pydantic.template import Template
from protobuf_to_pydantic.desc_template import DescTemplate
The import path for custom templates changed in `v0.3.0`. `DescTemplate` was removed. [cite: GitHub v0.3.0 release]

This quickstart demonstrates how to convert a Protobuf Message object into a Pydantic `BaseModel` at runtime using `msg_to_pydantic_model`. It includes a minimal simulated Protobuf message for immediate execution. For actual use, `UserMessage` would be imported from your generated `_pb2.py` files.

import sys from typing import Type from pydantic import BaseModel, Field from google.protobuf.message import Message from google.protobuf import descriptor_pool, descriptor_pb2 from protobuf_to_pydantic import msg_to_pydantic_model # Simulate a generated protobuf message `demo_pb2.UserMessage` # In a real scenario, this would come from `import demo_pb2` pool = descriptor_pool.Default() descriptor = descriptor_pb2.DescriptorProto() descriptor.name = 'UserMessage' descriptor.field.add(name='uid', number=1, type=descriptor_pb2.FieldDescriptorProto.TYPE_STRING) descriptor.field.add(name='age', number=2, type=descriptor_pb2.FieldDescriptorProto.TYPE_INT32) descriptor.field.add(name='user_name', number=3, type=descriptor_pb2.FieldDescriptorProto.TYPE_STRING) pool.Add(descriptor) # Create a mock Message class based on the descriptor class UserMessage(Message): def __init__(self, uid='', age=0, user_name='', **kwargs): super().__init__(**kwargs) self.uid = uid self.age = age self.user_name = user_name DESCRIPTOR = pool.FindMessageTypeByName('UserMessage') # Convert the Protobuf Message object to a Pydantic BaseModel UserModel: Type[BaseModel] = msg_to_pydantic_model(UserMessage) # Example usage of the generated Pydantic model user_data = UserModel(uid='123', age=30, user_name='John Doe') print(user_data.model_dump_json(indent=2)) # Access field info # print({k: v.field_info for k, v in UserModel.__fields__.items()}) # For Pydantic v1 print({k: v.json_schema_extra for k, v in UserModel.model_fields.items()}) # For Pydantic v2+
protobuf-to-pydantic --version
Debug
Known issues
breakingThe import path for custom template functionality changed significantly in `v0.3.0`. Older code using `DescTemplate` will break.
fix
Update imports from `from protobuf_to_pydantic.desc_template import DescTemplate` to `from protobuf_to_pydantic.template import Template` and adjust usage accordingly. [cite: GitHub v0.3.0 release]
affects: >=0.3.0
breakingVersion `0.2.7` included urgent fixes that may have introduced breaking changes in internal APIs, impacting custom integrations or advanced usage.
fix
Carefully review the changelog and test existing code after upgrading to or past `v0.2.7`. Consult the official documentation for any API changes if issues arise. [cite: GitHub v0.2.7 release]
affects: 0.2.7
gotchaFor 'Plugin Mode' (generating code from `.proto` files using `protoc`), the `protoc` compiler must be installed and accessible in your system's PATH. The library itself does not bundle `protoc`.
fix
Install `protoc` (Protocol Buffer Compiler) from the official Protocol Buffers GitHub releases or via your system's package manager. Ensure it's in your system's PATH.
affects: All
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'protobuf_to_pydantic.desc_template'
Attempting to import `DescTemplate` after the `v0.3.0` release, where its import path was changed to `Template`.
fix
Change the import statement to `from protobuf_to_pydantic.template import Template`.
FileNotFoundError: [Errno 2] No such file or directory: 'protoc'
The `protoc` command-line tool, required for compiling `.proto` files in plugin mode, is not installed or not found in the system's PATH.
fix
Install the Protocol Buffer Compiler (`protoc`) for your operating system and ensure its executable is discoverable in your system's PATH environment variable.
TypeError: 'Struct' object cannot be interpreted as a dict (or similar error when passing google.protobuf.struct_pb2.Struct)
Older versions of the library might have had issues correctly processing `google.protobuf.Struct` types into Pydantic models. [cite: GitHub v0.2.5 fix]
fix
Upgrade to `protobuf-to-pydantic` version `0.2.5` or newer, which includes a fix for handling `google.protobuf.Struct` types correctly.
Upgrade
Version history
0.3.3.1latest on PyPI · released Jun 7, 2025
Audit
Dependencies
pydanticrequiredCore functionality relies on Pydantic for model generation and validation.
protobufrequiredRequired for parsing Protobuf message definitions and handling generated `_pb2.py` files.
grpcio-toolsoptionalRequired for compiling .proto files and using the `protoc` plugin mode.
mypy-protobufoptionalOptional dependency for enhanced type checking and full functionality via `mypy-protobuf` integration.
Agent activity
6 hits · last 30 days
node
6
Resources
protobuf-to-pydantic — pip install protobuf-to-pydantic · libregistry