protobuf-decoder

0.4.0 verified Mon Apr 27 auth: no python

A Python library to decode Protocol Buffers (protobuf) without requiring the original .proto file. It can parse raw binary data and output a human-readable structure. Current version: 0.4.0, released June 2023. Development appears low-activity but stable, with several releases since 2022.

pip install protobuf-decoder

Common errors

error ImportError: cannot import name 'ProtobufDecoder' from 'protobuf_decoder' (unknown location) ↓

cause The library is not installed or the install name is wrong.

fix

Run pip install protobuf-decoder. Note the hyphen in pip install, but the import uses underscore.

error TypeError: object of type 'NoneType' has no len() ↓

cause Passing `None` as the raw protobuf data to the decoder.

fix

Ensure the input is a bytes-like object. Validate that the data is not None before passing.

Warnings

gotcha The library does not reconstruct .proto schema or generate human-readable field names. It only outputs field numbers and unknown field types. If you need field names, you must supply a .proto file (this lib doesn't support it). ↓

fix Use official protobuf compiler or schema-based tools for field name resolution.

gotcha When using the ProtobufDecoder class, you must call .decode() to get the parsed fields. The constructor itself does not parse immediately. ↓

fix Always call .decode() on the decoder instance, or use the convenience `parse()` function.

gotcha The `to_dict()` method (added in v0.4.0) may return a flat dictionary with field numbers as string keys. It does not handle nested message structures perfectly; nested data may be represented as bytes or as sub-dictionaries depending on detection. ↓

fix Check the output carefully; consider using `strict_mode` parameter if available to control nested parsing.

Imports

ProtobufDecoder

wrong

from protobuf_decoder.protobuf import ProtobufDecoder

correct

from protobuf_decoder import ProtobufDecoder

Common mistake: trying to import from a submodule that doesn't exist

parse

wrong

from protobuf_decoder import decode

correct

from protobuf_decoder import parse

The function is named `parse`, not `decode`

Quickstart

Basic usage: decode a raw protobuf message to a list of decoded fields.

from protobuf_decoder import ProtobufDecoder

# Example: decode a raw protobuf message
raw_protobuf = b'\x08\x96\x01'  # field 1, varint value 150

decoder = ProtobufDecoder(raw_protobuf)
decoded = decoder.decode()
print(decoded)  # [{'field_number': 1, 'field_name': '1', 'field_type': 'VarintValue', 'value': 150}]

# Or use the parse function directly
from protobuf_decoder import parse
decoded = parse(raw_protobuf)
print(decoded)  # same result