Install & Compatibility
Where this runs
tested against v3.3.10 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 20.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.1s · import 0.000s · 21MB
19MB installed
● package 19MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
protol
✓ This library is primarily used as a command-line tool named `protol`.
✗ import thing2_pb2 as thing2__pb2
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`.
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'
protol --version
Debug
Known issues
gotchaThe 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.fixRun `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`).
affects: All versions where `protoc` Python output creates absolute imports.
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.fixIntegrate `protol` into your build/generation pipeline as a CLI step (e.g., in a Makefile or shell script) immediately after running `protoc`.
affects: All versions
gotcha`protoletariat` relies on the `protoc` executable being installed and available in your system's PATH to inspect `FileDescriptorProtos` and correctly identify generated imports.fixEnsure `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`.
affects: All versions
Upgrade
Version history
3.3.10latest on PyPI · released Mar 19, 2025
Audit
Dependencies
protobufrequiredCore dependency for working with Protocol Buffers; its generated code is the target of protoletariat's transformations.
grpcio-toolsoptionalUsed for gRPC code generation, which often suffers from the same import issues as standard protobuf generation.
clickrequiredProvides the command-line interface for the `protol` tool.