protoletariat

What it is and what it does

Protoletariat is a command-line tool that fixes Python imports in code generated by protoc (the Protocol Buffers compiler). When protoc generates Python modules from .proto files, it creates absolute imports that don't work well in packaged Python code; protoletariat rewrites those imports to relative imports by analyzing the FileDescriptorProtos and applying AST-based rewrite rules.

The tool is designed as a post-processing step: you run protoc first to generate the Python code, then run protoletariat to fix the imports. It supports multiple input sources (protoc, buf, or raw FileDescriptorSet bytes) and can recursively create __init__.py files to turn output directories into proper packages. It depends on astunparse for AST manipulation, click for CLI handling, and protobuf for descriptor parsing.

Use it for:

• Fix broken imports in protoc-generated Python code when building a Python package that uses Protocol Buffers.
• Automate the import rewriting step in a build pipeline that generates gRPC service stubs and message types.
• Convert absolute imports to relative imports in generated protobuf modules to enable proper package distribution.
• Process code generated by buf (the modern protobuf build system) to make imports work in Python packages.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Protoletariat rewrites Python imports generated by protoc, converting absolute imports to relative imports so that generated protobuf code works correctly in Python packages.

No. The package is archived and abandoned, with no maintenance since June 2026. While it has low install friction and permissive licensing, the lack of active development creates risk for compatibility issues with future protobuf or Python versions. If you need to fix protoc-generated imports, consider whether the problem is still relevant with current protobuf versions or whether an actively maintained alternative exists.

Install

protoletariat on PyPI

pip install protoletariat

uv add protoletariat

poetry add protoletariat

Installing protoletariat

Before you install

Low friction install with three lightweight runtime dependencies (astunparse, click, protobuf). However, the package is archived and abandoned as of the last commit on 2026-06-04, with no active maintenance.

License in practice

Licensed under Apache-2.0 (permissive), so you can use it freely in commercial and open-source projects without significant legal constraints.

Quickstart

pip install protoletariat

# After running protoc to generate Python code:
protol --create-package --in-place --python-out out protoc --proto-path=. thing.proto

# This converts absolute imports to relative imports in the generated files.

Requires protoc to be installed and available on your system path; protoletariat is a post-processing tool that runs after protoc generates code.

Verify before relying

• Whether the abandoned status and lack of recent maintenance pose compatibility risks with future protobuf or Python versions.
• Whether the import rewriting approach remains compatible with current protoc output and gRPC code generation.

Package facts

Evidence: protoletariat-3.3.10-py3-none-any.whl

Tags

More Build Tools packages