# PBReflect
[](https://pypi.org/project/pbreflect)
[](https://pypi.python.org/pypi/pbreflect)
[](https://github.com/ValeriyMenshikov/pbreflect/actions/workflows/python-test.yml)
[](https://github.com/ValeriyMenshikov/pbreflect/blob/main/LICENSE)
[](https://pypistats.org/packages/pbreflect)
[](https://github.com/astral-sh/ruff)
PBReflect is a powerful tool for recovering Protocol Buffer (protobuf) definitions from gRPC services using the reflection API. It allows developers to generate `.proto` files from running gRPC servers without having access to the original source code.
## Features
- **Automatic Discovery**: Automatically discovers all services and messages exposed by a gRPC server
- **Proto Generation**: Generates complete `.proto` files with proper package structure
- **TLS Support**: Supports secure connections with custom certificates
- **Dependency Resolution**: Correctly handles dependencies between proto files
- **Simple CLI**: Easy-to-use command-line interface
- **Client Generation**: Generate Python client libraries from `.proto` files with multiple generator strategies
- **Custom Templates**: Support for custom code generation templates
- **All-in-One Command**: Generate client code directly from a gRPC server in a single step
## Installation
```bash
# Install using pip
pip install pbreflect
# Or using Poetry
poetry add pbreflect
```
## Quick Start
### Direct Client Generation from Server
PBReflect provides an all-in-one command to generate client code directly from a gRPC server:
```bash
# Generate client code directly from a gRPC server
pbreflect reflect -h localhost:50051 -o ./clients
```
This command:
1. Connects to the gRPC server
2. Retrieves proto definitions using reflection
3. Generates client code in one step
4. Automatically cleans up temporary proto files
You can customize the generation with various options:
```bash
# Generate custom client code directly from a server
pbreflect reflect -h localhost:50051 -o ./clients --gen-type pbreflect --template-dir ./my-templates
```
For secure connections, you can use TLS certificates:
```bash
# With TLS support
pbreflect reflect -h secure.example.com:443 -o ./clients \
--root-cert ./certs/ca.pem \
--private-key ./certs/client.key \
--cert-chain ./certs/client.pem
```
### Recovering Proto Files Only
If you only need to recover proto files from a gRPC server:
```bash
# Basic usage
pbreflect get-protos -h localhost:50051 -o ./protos
```
This will connect to the gRPC server at `localhost:50051`, retrieve all available proto definitions, and save them to the `./protos` directory.
#### Using TLS/SSL
For secure connections, you can use TLS certificates:
```bash
# With root certificate only
pbreflect get-protos -h secure.example.com:443 -o ./protos --root-cert ./certs/ca.pem
# With full client authentication
pbreflect get-protos -h secure.example.com:443 -o ./protos \
--root-cert ./certs/ca.pem \
--private-key ./certs/client.key \
--cert-chain ./certs/client.pem
```
### Client Code Generation from Proto Files
If you already have proto files and want to generate client code:
```bash
# Generate client code from proto files
pbreflect generate --proto-dir ./protos --output-dir ./generated --gen-type pbreflect
```
#### Generator Strategies
PBReflect supports multiple code generation strategies:
- **default**: Standard protoc Python output
- **mypy**: Standard output with mypy type annotations
- **betterproto**: Uses betterproto generator for more Pythonic API
- **pbreflect**: Custom generator with enhanced gRPC client support
Example:
```bash
# Generate code using the betterproto strategy
pbreflect generate --proto-dir ./protos --output-dir ./generated --gen-type betterproto
```
#### Custom Templates
For the `pbreflect` generator strategy, you can specify a custom templates directory:
```bash
# Generate code using custom templates
pbreflect generate --proto-dir ./protos --output-dir ./generated --gen-type pbreflect --template-dir ./my-templates
```
This allows you to customize the generated code according to your needs.
## CLI Commands
PBReflect provides a comprehensive CLI interface:
```
pbreflect reflect # Generate client code directly from a gRPC server (all-in-one)
pbreflect get-protos # Recover proto files from a running gRPC server
pbreflect generate # Generate client code from proto files
pbreflect info # Display information about available services
```
Use `--help` with any command to see all available options.
## Programmatic Usage
You can also use PBReflect in your Python code:
```python
from pathlib import Path
from pbreflect.protorecover.recover_service import RecoverService
# Basic usage
with RecoverService("localhost:50051", Path("./protos")) as service:
service.recover_proto_files()
# With TLS
with RecoverService(
"secure.example.com:443",
Path("./protos"),
use_tls=True,
root_certificates_path=Path("./certs/ca.pem"),
private_key_path=Path("./certs/client.key"),
certificate_chain_path=Path("./certs/client.pem")
) as service:
service.recover_proto_files()
```
## Use Cases
- **API Exploration**: Discover and understand the API of a gRPC service
- **Client Development**: Generate client code for services without access to original proto files
- **Testing**: Create mock clients and servers for testing
- **Reverse Engineering**: Analyze and document existing gRPC services
- **Migration**: Help migrate from one gRPC implementation to another
## Requirements
- gRPC server with reflection service enabled
## How It Works
PBReflect uses the gRPC reflection service to query a server for its service definitions. The reflection service returns `FileDescriptorProto` messages, which PBReflect then processes to reconstruct the original `.proto` files.
The process involves:
1. Connecting to the gRPC server
2. Querying the reflection service for available services
3. Retrieving file descriptors for each service
4. Reconstructing the proto definitions with proper imports
5. Writing the generated proto files to disk
## Limitations
- The target gRPC server must have the reflection service enabled
- Some advanced proto features might not be perfectly reconstructed
- Comments from the original proto files are not recoverable
## Contributing
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines on:
- Setting up your development environment
- Running tests
- Code style and conventions
- Pull request process
- Issue reporting
## Publishing
For maintainers, we have documented the release process in [PUBLISHING.md](PUBLISHING.md), which covers:
- Version bumping
- Building packages
- Publishing to PyPI
- Creating GitHub releases
- Documentation updates
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Acknowledgments
- The gRPC team for creating the reflection service
- All contributors who have helped improve this tool
Raw data
{
"_id": null,
"home_page": "https://github.com/ValeriyMenshikov/pbreflect",
"name": "pbreflect",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": null,
"keywords": "grpc, protobuf, reflection, proto, protocol-buffers, code-generation",
"author": "Menshikov Valeriy Sergeevich",
"author_email": "valery.menshikov.1989@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/6d/6d/a467f800b012b21b5c5334aa86956c747cc70c3bf95cfa8f9d6bb775f64c/pbreflect-1.1.0.tar.gz",
"platform": null,
"description": "# PBReflect\n\n[](https://pypi.org/project/pbreflect)\n[](https://pypi.python.org/pypi/pbreflect)\n[](https://github.com/ValeriyMenshikov/pbreflect/actions/workflows/python-test.yml)\n[](https://github.com/ValeriyMenshikov/pbreflect/blob/main/LICENSE)\n[](https://pypistats.org/packages/pbreflect)\n[](https://github.com/astral-sh/ruff)\n\nPBReflect is a powerful tool for recovering Protocol Buffer (protobuf) definitions from gRPC services using the reflection API. It allows developers to generate `.proto` files from running gRPC servers without having access to the original source code.\n\n## Features\n\n- **Automatic Discovery**: Automatically discovers all services and messages exposed by a gRPC server\n- **Proto Generation**: Generates complete `.proto` files with proper package structure\n- **TLS Support**: Supports secure connections with custom certificates\n- **Dependency Resolution**: Correctly handles dependencies between proto files\n- **Simple CLI**: Easy-to-use command-line interface\n- **Client Generation**: Generate Python client libraries from `.proto` files with multiple generator strategies\n- **Custom Templates**: Support for custom code generation templates\n- **All-in-One Command**: Generate client code directly from a gRPC server in a single step\n\n## Installation\n\n```bash\n# Install using pip\npip install pbreflect\n\n# Or using Poetry\npoetry add pbreflect\n```\n\n## Quick Start\n\n### Direct Client Generation from Server\n\nPBReflect provides an all-in-one command to generate client code directly from a gRPC server:\n\n```bash\n# Generate client code directly from a gRPC server\npbreflect reflect -h localhost:50051 -o ./clients\n```\n\nThis command:\n1. Connects to the gRPC server\n2. Retrieves proto definitions using reflection\n3. Generates client code in one step\n4. Automatically cleans up temporary proto files\n\nYou can customize the generation with various options:\n\n```bash\n# Generate custom client code directly from a server\npbreflect reflect -h localhost:50051 -o ./clients --gen-type pbreflect --template-dir ./my-templates\n```\n\nFor secure connections, you can use TLS certificates:\n\n```bash\n# With TLS support\npbreflect reflect -h secure.example.com:443 -o ./clients \\\n --root-cert ./certs/ca.pem \\\n --private-key ./certs/client.key \\\n --cert-chain ./certs/client.pem\n```\n\n### Recovering Proto Files Only\n\nIf you only need to recover proto files from a gRPC server:\n\n```bash\n# Basic usage\npbreflect get-protos -h localhost:50051 -o ./protos\n```\n\nThis will connect to the gRPC server at `localhost:50051`, retrieve all available proto definitions, and save them to the `./protos` directory.\n\n#### Using TLS/SSL\n\nFor secure connections, you can use TLS certificates:\n\n```bash\n# With root certificate only\npbreflect get-protos -h secure.example.com:443 -o ./protos --root-cert ./certs/ca.pem\n\n# With full client authentication\npbreflect get-protos -h secure.example.com:443 -o ./protos \\\n --root-cert ./certs/ca.pem \\\n --private-key ./certs/client.key \\\n --cert-chain ./certs/client.pem\n```\n\n### Client Code Generation from Proto Files\n\nIf you already have proto files and want to generate client code:\n\n```bash\n# Generate client code from proto files\npbreflect generate --proto-dir ./protos --output-dir ./generated --gen-type pbreflect\n```\n\n#### Generator Strategies\n\nPBReflect supports multiple code generation strategies:\n\n- **default**: Standard protoc Python output\n- **mypy**: Standard output with mypy type annotations\n- **betterproto**: Uses betterproto generator for more Pythonic API\n- **pbreflect**: Custom generator with enhanced gRPC client support\n\nExample:\n\n```bash\n# Generate code using the betterproto strategy\npbreflect generate --proto-dir ./protos --output-dir ./generated --gen-type betterproto\n```\n\n#### Custom Templates\n\nFor the `pbreflect` generator strategy, you can specify a custom templates directory:\n\n```bash\n# Generate code using custom templates\npbreflect generate --proto-dir ./protos --output-dir ./generated --gen-type pbreflect --template-dir ./my-templates\n```\n\nThis allows you to customize the generated code according to your needs.\n\n## CLI Commands\n\nPBReflect provides a comprehensive CLI interface:\n\n```\npbreflect reflect # Generate client code directly from a gRPC server (all-in-one)\npbreflect get-protos # Recover proto files from a running gRPC server\npbreflect generate # Generate client code from proto files\npbreflect info # Display information about available services\n```\n\nUse `--help` with any command to see all available options.\n\n## Programmatic Usage\n\nYou can also use PBReflect in your Python code:\n\n```python\nfrom pathlib import Path\nfrom pbreflect.protorecover.recover_service import RecoverService\n\n# Basic usage\nwith RecoverService(\"localhost:50051\", Path(\"./protos\")) as service:\n service.recover_proto_files()\n\n# With TLS\nwith RecoverService(\n \"secure.example.com:443\",\n Path(\"./protos\"),\n use_tls=True,\n root_certificates_path=Path(\"./certs/ca.pem\"),\n private_key_path=Path(\"./certs/client.key\"),\n certificate_chain_path=Path(\"./certs/client.pem\")\n) as service:\n service.recover_proto_files()\n```\n\n## Use Cases\n\n- **API Exploration**: Discover and understand the API of a gRPC service\n- **Client Development**: Generate client code for services without access to original proto files\n- **Testing**: Create mock clients and servers for testing\n- **Reverse Engineering**: Analyze and document existing gRPC services\n- **Migration**: Help migrate from one gRPC implementation to another\n\n## Requirements\n\n- gRPC server with reflection service enabled\n\n## How It Works\n\nPBReflect uses the gRPC reflection service to query a server for its service definitions. The reflection service returns `FileDescriptorProto` messages, which PBReflect then processes to reconstruct the original `.proto` files.\n\nThe process involves:\n\n1. Connecting to the gRPC server\n2. Querying the reflection service for available services\n3. Retrieving file descriptors for each service\n4. Reconstructing the proto definitions with proper imports\n5. Writing the generated proto files to disk\n\n## Limitations\n\n- The target gRPC server must have the reflection service enabled\n- Some advanced proto features might not be perfectly reconstructed\n- Comments from the original proto files are not recoverable\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines on:\n\n- Setting up your development environment\n- Running tests\n- Code style and conventions\n- Pull request process\n- Issue reporting\n\n## Publishing\n\nFor maintainers, we have documented the release process in [PUBLISHING.md](PUBLISHING.md), which covers:\n\n- Version bumping\n- Building packages\n- Publishing to PyPI\n- Creating GitHub releases\n- Documentation updates\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Acknowledgments\n\n- The gRPC team for creating the reflection service\n- All contributors who have helped improve this tool",
"bugtrack_url": null,
"license": "MIT",
"summary": "A tool for recovering Protocol Buffer definitions from gRPC services using reflection API and generating client code",
"version": "1.1.0",
"project_urls": {
"Homepage": "https://github.com/ValeriyMenshikov/pbreflect",
"Repository": "https://github.com/ValeriyMenshikov/pbreflect"
},
"split_keywords": [
"grpc",
" protobuf",
" reflection",
" proto",
" protocol-buffers",
" code-generation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c228a1a71b39fbe907a52a879d7108f808b403f377b381e163306785988f3671",
"md5": "7e3a0b6d7365cd9c0ed3a5490229397d",
"sha256": "32b5c98be811b26c55e34761fdd53ef79369c85e80ec2da34c41cfe64de36c50"
},
"downloads": -1,
"filename": "pbreflect-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7e3a0b6d7365cd9c0ed3a5490229397d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 51546,
"upload_time": "2025-08-03T17:44:13",
"upload_time_iso_8601": "2025-08-03T17:44:13.032692Z",
"url": "https://files.pythonhosted.org/packages/c2/28/a1a71b39fbe907a52a879d7108f808b403f377b381e163306785988f3671/pbreflect-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6d6da467f800b012b21b5c5334aa86956c747cc70c3bf95cfa8f9d6bb775f64c",
"md5": "425ceeff9abc36e39003b36d48fd73b9",
"sha256": "8d94bcfc3aeacd452d329971aad4a20b865e769012a0f9af8b1abeb04841f2d6"
},
"downloads": -1,
"filename": "pbreflect-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "425ceeff9abc36e39003b36d48fd73b9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 40922,
"upload_time": "2025-08-03T17:44:14",
"upload_time_iso_8601": "2025-08-03T17:44:14.267483Z",
"url": "https://files.pythonhosted.org/packages/6d/6d/a467f800b012b21b5c5334aa86956c747cc70c3bf95cfa8f9d6bb775f64c/pbreflect-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-03 17:44:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ValeriyMenshikov",
"github_project": "pbreflect",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pbreflect"
}
JSON
