Blackbox Protobuf

1.4.2 verified Fri May 01 auth: no python

Library for encoding and decoding protobuf messages without needing a .proto type definition. It infers the schema automatically and supports repeated fields, enums, and nested messages. Current version 1.4.2, supports Python 3.8+, released irregularly.

pip install bbpb

Common errors

error ImportError: No module named 'blackboxprotobuf' ↓

cause Importing using the full library name instead of 'bbpb'.

fix

Install bbpb and import as 'from bbpb import ...'.

error TypeError: decode_message() missing 1 required positional argument: 'data' ↓

cause Passing a byte string as the second argument, but the function signature changed in v1.4.0.

fix

Update to v1.4.0+ and use: result = decode_message(blob); data = result['data']; typedef = result['typedef'].

error ValueError: Unknown wire type 5 ↓

cause Encountered a protobuf field with wire type 5 (32-bit group start) which is not supported.

fix

This library does not support groups. Use the original .proto file and protobuf library instead.

Warnings

breaking Version 1.4.0 changed the return format of decode_message: it now returns a dict with 'data' and 'typedef' keys, not a tuple. Old code expecting a tuple will break. ↓

fix Update code to handle dict: result = decode_message(blob); data = result['data']; typedef = result['typedef']

gotcha The library does not support all protobuf features (e.g. groups, maps, oneofs). It may misinterpret or skip unsupported wire types silently. ↓

fix Test against known messages; verify round-trip encoding/decoding. For complex schemas, consider using actual .proto files.

deprecated The function 'decode_message_with_type' is deprecated since v1.3.0 and removed in v1.4.0. Use decode_message instead. ↓

fix Replace decode_message_with_type(blob, typedef) with decode_message(blob, typedef). Note the return format change.

gotcha Field numbers are treated as keys in the data dict; they are integers, not strings. Attempting to access by string will fail. ↓

fix Use integer keys: data[1] not data['1']. The typedef dict uses string keys for field numbers.

Imports

encode_message
wrong
```
from blackboxprotobuf import encode_message
```
correct
```
from bbpb import encode_message
```
The package is imported as 'bbpb', not the full name 'blackboxprotobuf'.
decode_message
wrong
```
from blackboxprotobuf.lib import decode_message
```
correct
```
from bbpb import decode_message
```
Direct import from top-level 'bbpb' package, not from submodule 'lib'.
decode_message
wrong
```
from bbpb.decode import decode_message
```
correct
```
from bbpb import decode_message
```
There is no separate 'decode' submodule; the function is in __init__.

Quickstart

Decode and encode protobuf binary data without a .proto file. The library infers a type definition (typedef) that can be reused for encoding.

from bbpb import decode_message, encode_message

# Example protobuf raw bytes (from a known message)
raw_bytes = b'\x08\x96\x01'  # field 1, varint 150

# Decode to a plain data structure
decoded = decode_message(raw_bytes)
print(decoded)  # {'data': {1: 150}, 'typedef': {'1': {'type': 'uint'}}}

# Modify and re-encode
encoded = encode_message({'data': {1: 200}}, decoded['typedef'])
print(encoded.hex())  # 08c801