Python Protoletariat

3.3.10 · active · verified Sat Apr 11

Protoletariat is a Python utility designed to address the long-standing issue of absolute imports in Python code generated by the official Protocol Buffers compiler (`protoc`). It acts as a post-processing step, rewriting these problematic absolute imports into correct relative imports, enabling smoother integration of generated protobuf code within Python packages. The library is actively maintained with frequent dependency updates.

Warnings

gotcha The official `protoc` compiler generates Python code with absolute imports (e.g., `import other_pb2`) which often leads to `ModuleNotFoundError` when the generated files are part of a Python package or module structure. `protoletariat` is designed specifically to fix this post-generation.
Fix: Run `protol` as a post-processing step on your `protoc`-generated Python files, typically with `--create-package --in-place` options, as shown in the quickstart. This will rewrite absolute imports to relative ones (`from . import other_pb2`).
gotcha `protoletariat` is primarily a command-line tool (`protol`) that modifies generated Python `.py` files in-place. It is not generally intended for direct programmatic import and use within application code to fix imports at runtime.
Fix: Integrate `protol` into your build/generation pipeline as a CLI step (e.g., in a Makefile or shell script) immediately after running `protoc`.
gotcha `protoletariat` relies on the `protoc` executable being installed and available in your system's PATH to inspect `FileDescriptorProtos` and correctly identify generated imports.
Fix: Ensure `protoc` (the Protocol Buffer compiler) is installed and its executable is accessible via your system's PATH. On macOS, `brew install protobuf` often resolves this. Users should also ensure their `protoc` version is compatible with the `protobuf` runtime used by `protoletariat`.

Install

pip install protoletariat Install from PyPI

Imports

protol
```
This library is primarily used as a command-line tool named `protol`.
```
The 'wrong' import pattern is what `protoc` typically generates for inter-proto file dependencies, which `protol` then fixes to `from . import thing2_pb2 as thing2__pb2`.

Quickstart

This quickstart demonstrates the core workflow of `protoletariat`. It involves defining two `.proto` files with a dependency, generating Python stubs using `protoc`, and then using the `protol` command-line tool to convert the absolute imports generated by `protoc` into relative imports for proper Python package structure. The `--create-package` flag creates an `__init__.py` file if it doesn't exist, making the output directory a valid Python package.

mkdir -p out protos
cat <<EOF > protos/thing1.proto
syntax = "proto3";
import "thing2.proto";
package things;
message Thing1 { Thing2 thing2 = 1; }
EOF
cat <<EOF > protos/thing2.proto
syntax = "proto3";
package things;
message Thing2 { string data = 1; }
EOF

# Step 1: Generate Python code with protoc
protoc \
  --python_out=out \
  --proto_path=protos protos/thing1.proto protos/thing2.proto

echo "\n--- Before protoletariat ---"
cat out/thing1_pb2.py | grep 'import thing2_pb2'

# Step 2: Fix imports with protol
protol \
  --create-package \
  --in-place \
  --python-out out \
  --proto-path=protos protos/thing1.proto protos/thing2.proto

echo "\n--- After protoletariat ---"
cat out/thing1_pb2.py | grep 'import thing2_pb2'

# Expected output shows 'from . import thing2_pb2'

view raw JSON →