{"id":4178,"library":"protoletariat","title":"Python Protoletariat","description":"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.","status":"active","version":"3.3.10","language":"en","source_language":"en","source_url":"https://github.com/cpcloud/protoletariat","tags":["protobuf","grpc","code generation","imports","tooling","cli"],"install":[{"cmd":"pip install protoletariat","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"Core dependency for working with Protocol Buffers; its generated code is the target of protoletariat's transformations.","package":"protobuf","optional":false},{"reason":"Used for gRPC code generation, which often suffers from the same import issues as standard protobuf generation.","package":"grpcio-tools","optional":true},{"reason":"Provides the command-line interface for the `protol` tool.","package":"click","optional":false}],"imports":[{"note":"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`.","wrong":"import thing2_pb2 as thing2__pb2","symbol":"protol","correct":"This library is primarily used as a command-line tool named `protol`."}],"quickstart":{"code":"mkdir -p out protos\ncat <<EOF > protos/thing1.proto\nsyntax = \"proto3\";\nimport \"thing2.proto\";\npackage things;\nmessage Thing1 { Thing2 thing2 = 1; }\nEOF\ncat <<EOF > protos/thing2.proto\nsyntax = \"proto3\";\npackage things;\nmessage Thing2 { string data = 1; }\nEOF\n\n# Step 1: Generate Python code with protoc\nprotoc \\\n  --python_out=out \\\n  --proto_path=protos protos/thing1.proto protos/thing2.proto\n\necho \"\\n--- Before protoletariat ---\"\ncat out/thing1_pb2.py | grep 'import thing2_pb2'\n\n# Step 2: Fix imports with protol\nprotol \\\n  --create-package \\\n  --in-place \\\n  --python-out out \\\n  --proto-path=protos protos/thing1.proto protos/thing2.proto\n\necho \"\\n--- After protoletariat ---\"\ncat out/thing1_pb2.py | grep 'import thing2_pb2'\n\n# Expected output shows 'from . import thing2_pb2'","lang":"bash","description":"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."},"warnings":[{"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`).","message":"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.","severity":"gotcha","affected_versions":"All versions where `protoc` Python output creates absolute imports."},{"fix":"Integrate `protol` into your build/generation pipeline as a CLI step (e.g., in a Makefile or shell script) immediately after running `protoc`.","message":"`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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"`protoletariat` relies on the `protoc` executable being installed and available in your system's PATH to inspect `FileDescriptorProtos` and correctly identify generated imports.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}