### Use protol raw subcommand

Source: https://context7.com/cpcloud/protoletariat/llms.txt

Examples for rewriting imports using pre-generated FileDescriptorSet bytes from files or stdin.

```bash
# Generate FileDescriptorSet file first
protoc \
  --include_imports \
  --descriptor_set_out=descriptor.bin \
  --proto_path=./protos \
  thing1.proto thing2.proto

# Use raw subcommand with file
protol \
  --python-out ./gen \
  --in-place \
  --create-package \
  raw descriptor.bin

# Use raw subcommand with stdin
cat descriptor.bin | protol \
  --python-out ./gen \
  --in-place \
  raw -

# Pipe from protoc directly
protoc \
  --include_imports \
  --descriptor_set_out=/dev/stdout \
  --proto-path=./protos \
  service.proto | protol \
    --python-out ./gen \
    --in-place \
    raw -
```

--------------------------------

### Define Protobuf Files

Source: https://github.com/cpcloud/protoletariat/blob/main/README.md

Example protobuf definitions for testing import resolution.

```protobuf
// thing1.proto
syntax = "proto3";

import "thing2.proto";

package things;

message Thing1 {
  Thing2 thing2 = 1;
}
```

```protobuf
// thing2.proto
syntax = "proto3";

package things;

message Thing2 {
  string data = 1;
}
```

--------------------------------

### Use protol protoc subcommand

Source: https://context7.com/cpcloud/protoletariat/llms.txt

Examples for generating FileDescriptorSet data using the protoc compiler via the protol CLI.

```bash
# Basic protoc usage with single proto path
protol \
  --python-out ./gen \
  --in-place \
  --create-package \
  protoc \
    --proto-path=./protos \
    thing1.proto thing2.proto

# Multiple proto paths
protol \
  --python-out ./gen \
  --in-place \
  protoc \
    --proto-path=./protos \
    --proto-path=./vendor/protos \
    api/service.proto api/messages.proto

# Custom protoc path via environment variable
PROTOC_PATH=/usr/local/bin/protoc protol \
  --python-out ./gen \
  --in-place \
  protoc \
    --proto-path=./protos \
    myservice.proto

# Using grpc_tools.protoc (Python grpcio-tools)
protol \
  --python-out ./gen \
  --in-place \
  protoc \
    --protoc-path "python -m grpc_tools.protoc" \
    --proto-path=./protos \
    service.proto
```

--------------------------------

### Use protol buf subcommand

Source: https://context7.com/cpcloud/protoletariat/llms.txt

Examples for using the buf build tool to generate FileDescriptorSet data for import rewriting.

```bash
# Basic buf usage (current directory)
protol \
  --python-out ./gen \
  --in-place \
  --create-package \
  buf .

# Specify input directory
protol \
  --python-out ./gen \
  --in-place \
  buf ./proto

# Custom buf executable path
BUF_PATH=/usr/local/bin/buf protol \
  --python-out ./gen \
  --in-place \
  buf .
```

--------------------------------

### Run protol CLI commands

Source: https://context7.com/cpcloud/protoletariat/llms.txt

Common CLI usage patterns for rewriting imports using protoc, buf, or raw descriptor sets.

```bash
# Basic usage with protoc
protol \
  --python-out out \
  --in-place \
  --create-package \
  protoc --proto-path=./protos thing1.proto thing2.proto

# Usage with buf
protol \
  --python-out out \
  --in-place \
  --create-package \
  buf .

# Preview changes without modifying files (no --in-place)
protol \
  --python-out generated \
  protoc --proto-path=./protos myservice.proto

# Specify custom module suffixes
protol \
  --python-out out \
  --in-place \
  --module-suffixes "_pb2.py" \
  --module-suffixes "_pb2.pyi" \
  protoc --proto-path=./protos api.proto

# Exclude certain imports from rewriting
protol \
  --python-out out \
  --in-place \
  --exclude-imports-glob "google/protobuf/*" \
  --exclude-imports-glob "mycompany/shared/*" \
  protoc --proto-path=./protos service.proto
```

--------------------------------

### End-to-End Protobuf Workflow

Source: https://context7.com/cpcloud/protoletariat/llms.txt

A complete workflow for generating protobuf code and fixing imports for Python packages.

```bash
# Step 1: Create proto files
mkdir -p protos/things

cat > protos/thing1.proto << 'EOF'
syntax = "proto3";

import "thing2.proto";

package things;

message Thing1 {
  Thing2 thing2 = 1;
}
EOF

cat > protos/thing2.proto << 'EOF'
syntax = "proto3";

package things;

message Thing2 {
  string data = 1;
}
EOF

# Step 2: Generate Python code with protoc
mkdir -p gen
protoc \
  --python_out=gen \
  --proto_path=protos \
  thing1.proto thing2.proto

# Step 3: Fix imports with protoletariat
protol \
  --create-package \
  --in-place \
  --python-out gen \
  protoc --proto-path=protos thing1.proto thing2.proto

# Result: gen/thing1_pb2.py now has:
# -import thing2_pb2 as thing2__pb2
# +from . import thing2_pb2 as thing2__pb2

# Step 4: Import in Python
python -c "
import sys
sys.path.insert(0, 'gen')
from gen import thing1_pb2, thing2_pb2
t2 = thing2_pb2.Thing2(data='hello')
t1 = thing1_pb2.Thing1(thing2=t2)
print(t1)
"
```

--------------------------------

### View Import Diff

Source: https://github.com/cpcloud/protoletariat/blob/main/README.md

Expected change in the generated Python module after running protol.

```patch
-import thing2_pb2 as thing2__pb2
-
+from . import thing2_pb2 as thing2__pb2
```

--------------------------------

### Generate Python Code with protoc

Source: https://github.com/cpcloud/protoletariat/blob/main/README.md

Standard command to generate Python code from protobuf files.

```sh
$ mkdir out
$ protoc \
  --python_out=out \
  --proto_path=directory/containing/protos thing1.proto thing2.proto
```

--------------------------------

### Generate gRPC Service Definitions

Source: https://context7.com/cpcloud/protoletariat/llms.txt

Generate gRPC code and fix imports for both Python source and mypy type stubs.

```bash
# Create service proto
cat > protos/service.proto << 'EOF'
syntax = "proto3";

import "thing1.proto";
import "thing2.proto";

package things;

service ThingService {
    rpc GetThing1(Thing1) returns (Thing1) {}
    rpc GetThing2(Thing2) returns (Thing2) {}
}
EOF

# Generate Python code with gRPC and mypy support
protoc \
  --python_out=gen \
  --grpc_python_out=gen \
  --mypy_out=gen \
  --mypy_grpc_out=gen \
  --plugin=protoc-gen-grpc_python=$(which grpc_python_plugin) \
  --proto_path=protos \
  thing1.proto thing2.proto service.proto

# Fix all imports including gRPC stubs
protol \
  --create-package \
  --in-place \
  --python-out gen \
  --module-suffixes "_pb2.py" \
  --module-suffixes "_pb2.pyi" \
  --module-suffixes "_pb2_grpc.py" \
  --module-suffixes "_pb2_grpc.pyi" \
  protoc --proto-path=protos thing1.proto thing2.proto service.proto
```

--------------------------------

### Generate with Raw FileDescriptorSet

Source: https://context7.com/cpcloud/protoletariat/llms.txt

Use the Raw generator to process pre-generated FileDescriptorSet bytes.

```python
with open("descriptor.bin", "rb") as f:
    fdset_bytes = f.read()

raw_gen = Raw(fdset_bytes)
raw_gen.fix_imports(
    python_out=Path("./gen"),
    create_package=False,
    overwrite_callback=write_callback,
    module_suffixes=["_pb2.py"],
    exclude_imports_glob=[]
)
```

--------------------------------

### Rewrite Imports with ASTImportRewriter

Source: https://context7.com/cpcloud/protoletariat/llms.txt

Use the low-level ASTImportRewriter API to programmatically register and apply import replacements.

```python
from protoletariat.rewrite import ASTImportRewriter, build_rewrites, Replacement

# Create rewriter and register replacements
rewriter = ASTImportRewriter()

# Build rewrites for a proto dependency relationship
# proto="a/b/c" depends on dep="foo/bar"
replacements = build_rewrites(proto="a/b/c", dep="foo/bar", is_public=False)
# Returns:
# [Replacement(old='from foo import bar_pb2 as foo_dot_bar__pb2',
#              new='from ...foo import bar_pb2 as foo_dot_bar__pb2'),
#  Replacement(old='import foo.bar_pb2', new='from ... import foo')]

for repl in replacements:
    rewriter.register_rewrite(repl)

# Rewrite source code
original_code = """
import thing2_pb2 as thing2__pb2
from foo import bar_pb2 as foo_dot_bar__pb2

class MyMessage:
    pass
"""

rewritten_code = rewriter.rewrite(original_code)
# Converts absolute imports to relative imports

# Manual replacement registration
manual_replacement = Replacement(
    old="import mypackage_pb2 as mypackage__pb2",
    new="from . import mypackage_pb2 as mypackage__pb2"
)
rewriter.register_rewrite(manual_replacement)
```

--------------------------------

### Fix Imports with protol

Source: https://github.com/cpcloud/protoletariat/blob/main/README.md

Post-processing command to convert absolute imports to relative imports in generated Python files.

```sh
$ protol \
  --create-package \
  --in-place \
  --python-out out \
  protoc --proto-path=directory/containing/protos thing1.proto thing2.proto
```

--------------------------------

### Use FileDescriptorSetGenerator Python API

Source: https://context7.com/cpcloud/protoletariat/llms.txt

Programmatic usage of the FileDescriptorSetGenerator to fix imports using Protoc or Buf backends.

```python
from pathlib import Path
from protoletariat.fdsetgen import Protoc, Buf, Raw

# Using Protoc generator
protoc_gen = Protoc(
    protoc_path="protoc",
    proto_paths=[Path("./protos")],
    protoc_args=["thing1.proto", "thing2.proto"]
)

def write_callback(python_file: Path, code: str) -> None:
    python_file.write_text(code)

protoc_gen.fix_imports(
    python_out=Path("./gen"),
    create_package=True,
    overwrite_callback=write_callback,
    module_suffixes=["_pb2.py", "_pb2.pyi", "_pb2_grpc.py", "_pb2_grpc.pyi"],
    exclude_imports_glob=["google/protobuf/*"]
)

# Using Buf generator
buf_gen = Buf(buf_path="buf", input="./protos")
buf_gen.fix_imports(
    python_out=Path("./gen"),
    create_package=True,
    overwrite_callback=write_callback,
    module_suffixes=["_pb2.py"],
    exclude_imports_glob=[]
)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.