Registry / serialization / proto-plus

proto-plus

JSON →
library1.28.4pypypi✓ verified 29d ago

A Python library that provides a beautiful, Pythonic interface for working with protocol buffers. Current version: 1.27.2. Maintained with regular updates.

pip install proto-plus
INSTALL
IMPORT
SIG · PROTO-PLUS
P
proto-plus
serializationpythonv1.28.4
Install
2.1s avg
Import
253ms
Disk
18MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v1.28.4 · 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.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.380s · 19.9MB
glibc
py 3.10–3.95 runs
installs and imports cleanly · install 2.1s · import 0.126s · 21MB
18MB installed
● package 18MB
Code
Verified usage

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

proto
✓ import proto
Ensure 'proto' is imported to access the library's functionalities.
proto.Message
✓ from proto import Message
Import 'Message' from 'proto' to define protocol buffer messages.

A simple example demonstrating how to define and use protocol buffer messages with Proto Plus.

import proto class Composer(proto.Message): given_name = proto.Field(proto.STRING, number=1) family_name = proto.Field(proto.STRING, number=2) class Song(proto.Message): composer = proto.Field(Composer, number=1) title = proto.Field(proto.STRING, number=2) lyrics = proto.Field(proto.STRING, number=3) year = proto.Field(proto.INT32, number=4) song = Song( composer={'given_name': 'Johann', 'family_name': 'Pachelbel'}, title='Canon in D', year=1680, ) print(song.composer.family_name) # Output: Pachelbel print(song.title) # Output: Canon in D
Debug
Known issues
breakingProto Plus 1.27.0 introduced changes to the 'Field' class constructor, requiring explicit 'type' and 'number' arguments.
fix
Update your 'Field' class instantiations to include 'type' and 'number' arguments.
affects: 1.27.0
gotchaWhen defining nested messages, ensure that the nested class is defined before the parent class to avoid 'NameError'.
fix
Define nested message classes before the parent class to prevent 'NameError' during instantiation.
affects: All
gotchaRunning pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment.
fix
It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv
affects: All
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'your_app_name.proto.your_service_pb2'
This error occurs because the Python protobuf code has not been generated from your '.proto' file, or the generated files are not in a directory included in your Python import path (PYTHONPATH).
fix
Generate the Python code from your '.proto' files using the `protoc` compiler and ensure the output directory is in your `PYTHONPATH` or added to `sys.path`:
`protoc --python_out=. --proto_path=. your_service.proto`
AttributeError: 'MyProtoMessage' object has no attribute 'to_dict'
The `to_dict()` and `from_dict()` methods are enhancements provided by `proto-plus`, and this error indicates that `proto-plus` is either not installed, not correctly applied to your protobuf classes, or an older version is in use.
fix
Ensure `proto-plus` is installed (`pip install proto-plus`) and that your environment allows it to patch the protobuf classes. These methods should become available automatically when `proto-plus` is active.
TypeError: cannot interpret bytestring as UTF-8
This error arises when you attempt to assign a `bytes` object that is not a valid UTF-8 sequence to a protobuf field defined as a `string` type, which expects a Python `str` (unicode).
fix
Decode the `bytes` data into a `str` (unicode string) before assigning it to a protobuf `string` field, typically using `.decode('utf-8')`.
TypeError: Can't set repeated field to non-iterable
This error occurs when you try to assign a single scalar value (e.g., a string or integer) directly to a protobuf repeated field, which expects an iterable (like a list or tuple) of values.
fix
Always assign an iterable (even a list with a single item) to a repeated field.
Upgrade
Version history
1.28.4latest on PyPI · released Aug 25, 2026
Audit
Dependencies
protobufrequiredRequired for protocol buffer support
Agent activity
13 hits · last 30 days
node
12
Resources
proto-plus — pip install proto-plus · libregistry