{"id":13493556,"url":"https://github.com/cpcloud/protoletariat","last_synced_at":"2025-05-15T16:03:19.490Z","repository":{"id":36976156,"uuid":"430500677","full_name":"cpcloud/protoletariat","owner":"cpcloud","description":"Protocol Buffers for the rest of us","archived":false,"fork":false,"pushed_at":"2025-05-14T20:23:19.000Z","size":1262,"stargazers_count":180,"open_issues_count":20,"forks_count":9,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-05-14T21:28:51.617Z","etag":null,"topics":["ast","buf","grpc","import","protobuf","protocol-buffers","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cpcloud.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-11-21T22:58:27.000Z","updated_at":"2025-04-25T08:34:06.000Z","dependencies_parsed_at":"2024-03-25T11:26:14.832Z","dependency_job_id":"1372d930-411e-46e7-9500-65a7dee286a4","html_url":"https://github.com/cpcloud/protoletariat","commit_stats":{"total_commits":1089,"total_committers":10,"mean_commits":108.9,"dds":0.5638200183654729,"last_synced_commit":"67322ddbcea37f927efa3e88e3f6ac8e18f4e6cb"},"previous_names":[],"tags_count":66,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cpcloud%2Fprotoletariat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cpcloud%2Fprotoletariat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cpcloud%2Fprotoletariat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cpcloud%2Fprotoletariat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cpcloud","download_url":"https://codeload.github.com/cpcloud/protoletariat/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254233962,"owners_count":22036815,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ast","buf","grpc","import","protobuf","protocol-buffers","python"],"created_at":"2024-07-31T19:01:16.517Z","updated_at":"2025-05-15T16:03:19.427Z","avatar_url":"https://github.com/cpcloud.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Protocol Buffers for the Rest of Us\n\n[![CI](https://github.com/cpcloud/protoletariat/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/cpcloud/protoletariat/actions/workflows/ci.yml)\n\n## Motivation\n\nAre you annoyed by having to fix the absolute imports generated by `protoc`?\n\nIf so, then `protoletariat` is the tool for you.\n\n`protoletariat` has one goal: fixing the broken imports for the Python code\ngenerated by `protoc`.\n\nSee https://github.com/protocolbuffers/protobuf/issues/1491 for the discussion that inspired this tool.\n\n## Installation\n\n|   Artifact    |                                                              Status                                                               |                Installation Command                |\n| :-----------: | :-------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------: |\n| PyPI Package  |                  [![PyPI](https://img.shields.io/pypi/v/protoletariat)](https://pypi.org/project/protoletariat)                   |            `pip install protoletariat`             |\n| Conda Package | [![Conda Version](https://img.shields.io/conda/vn/conda-forge/protoletariat.svg)](https://anaconda.org/conda-forge/protoletariat) |    `conda install protoletariat -c conda-forge`    |\n| Docker Image  |                                                                 ∅                                                                 | `docker pull ghcr.io/cpcloud/protoletariat:latest` |\n\n**Note: the `conda-forge` package version may lag behind the other artifacts by a few hours.**\n\n## Usage\n\n`protoletariat` is designed to be run as a post-processing step _after_ running\n`protoc`. It operates directly on the generated code.\n\n### Example\n\nHere's an example of how to use the tool, called `protol`:\n\n1. Create a few protobuf files\n\n```protobuf\n// thing1.proto\nsyntax = \"proto3\";\n\nimport \"thing2.proto\";\n\npackage things;\n\nmessage Thing1 {\n  Thing2 thing2 = 1;\n}\n```\n\n```protobuf\n// thing2.proto\nsyntax = \"proto3\";\n\npackage things;\n\nmessage Thing2 {\n  string data = 1;\n}\n```\n\n2. Run `protoc` on those files\n\n```sh\n$ mkdir out\n$ protoc \\\n  --python_out=out \\\n  --proto_path=directory/containing/protos thing1.proto thing2.proto\n```\n\n3. Run `protol` on the generated code\n\n```sh\n$ protol \\\n  --create-package \\\n  --in-place \\\n  --python-out out \\\n  protoc --proto-path=directory/containing/protos thing1.proto thing2.proto\n```\n\nThe `out/thing1_pb2.py` module should show a diff containing at least these lines:\n\n```patch\n-import thing2_pb2 as thing2__pb2\n-\n+from . import thing2_pb2 as thing2__pb2\n```\n\n## How it works\n\nAt a high level `protoletariat` converts absolute imports to relative imports.\n\nHowever, it doesn't convert just any absolute import to a relative import.\n\nThe `protol` tool will only convert imports that were generated from `.proto`\nfiles. It does this by inspecting `FileDescriptorProtos` generated from the\nproto files.\n\nThe core rewrite mechanism is implemented using a simplified form of pattern\nmatching that looks at the Python AST, and invokes rewrite rules for matched\nimport patterns.\n\n## Subcommands\n\n`protoletariat` has a subcommand for each tool that you might like to use to\ngenerate `FileDescriptorSet` bytes:\n\n| Subcommand | Description                                                                |\n| :--------: | :------------------------------------------------------------------------- |\n|  `protoc`  | Uses `protoc` to generate `FileDescriptorSet` bytes                        |\n|   `buf`    | Uses `buf` to generate `FileDescriptorSet` bytes                           |\n|   `raw`    | You provide the `FileDescriptorSet` bytes as a file or directly from stdin |\n\n## Help\n\n```\n$ protol\nUsage: protol [OPTIONS] COMMAND [ARGS]...\n\n  Rewrite protoc or buf-generated imports for use by the protoletariat.\n\nOptions:\n  -o, --python-out DIRECTORY      Directory containing protoc or buf-generated Python code  [required]\n  --in-place / --not-in-place     Overwrite all relevant files under `--python-out` with adjusted imports  [default: not-in-place]\n  --create-package / --dont-create-package\n                                  Recursively create __init__.py files under `--python-out`  [default: dont-create-package]\n  -s, --module-suffixes TEXT      Suffixes of Python/mypy modules to process  [default: _pb2.py, _pb2.pyi, _pb2_grpc.py, _pb2_grpc.pyi]\n  --exclude-google-imports / --dont-exclude-google-imports\n                                  Exclude rewriting imports prefixed with google/protobuf\n  -e, --exclude-imports-glob TEXT\n                                  Exclude imports matching a glob pattern from being rewritten. Multiple values are allowed\n  --help                          Show this message and exit.\n\nCommands:\n  buf     Use buf to generate the FileDescriptorSet blob\n  protoc  Use protoc to generate the FileDescriptorSet blob\n  raw     Rewrite imports using FileDescriptorSet bytes from a file or stdin\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcpcloud%2Fprotoletariat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcpcloud%2Fprotoletariat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcpcloud%2Fprotoletariat/lists"}