Skip to content
Permalink
Browse files

documentation for grpcio (pantsbuild#7155)

### Problem

Documentation for grpcio generation tool
  • Loading branch information...
marcinex7 authored and baroquebobcat committed Feb 5, 2019
1 parent f73f112 commit b2f5a498de6e550d2a54b4fa4f64a739ee8d4f92
Showing with 58 additions and 0 deletions.
  1. +6 −0 src/docs/common_tasks/BUILD
  2. +50 −0 src/docs/common_tasks/python_proto_gen.md
  3. +2 −0 src/docs/docsite.json
@@ -132,3 +132,9 @@ page(
name='thrift_gen',
source='thrift_gen.md',
)


page(
name='python_proto_gen',
source='python_proto_gen.md',
)
@@ -0,0 +1,50 @@
# Python gRPC + protobufs

## Problem
You have `.proto` files defining protobufs and grpc services and you want Pants to generate Python code from them that you can use from a Python application.

## Solution
Create `python_grpc_library` targets and use the gen goal to generate code from the `.proto` files. There is a codegen task grpcio-run, that uses Python's grpcio library https://grpc.io/ and generates python code from .proto files.

## Usage

in a `BUILD` file near your proto files, create a `python_grpcio_library` target with your protos as a `sources`.

```build
python_grpcio_library(
sources=['service.proto'],
dependencies=[
'3rdparty/python:protobuf',
]
)
```

Then, you can add a dependency on this target in your python binary's `BUILD` file `dependencies` section:

```build
python_binary(
source='server.py',
dependencies=[
# [...]
'examples/src/protobuf/org/pantsbuild/example/grpcio/service'
],
)
```

## Example:
An example Python grpc client/server can be found in [/examples/src/python/example/grpcio](https://github.com/pantsbuild/pants/tree/master/examples/src/python/example/grpcio)

to create a gRPC server execute
```bash
./pants run examples/src/python/example/grpcio/server
```

and when server is running, run client example:
```bash
./pants run examples/src/python/example/grpcio/client
```

generated code can be found as usual in pants output directory:
```bash
./pants.d/gen/grpcio-run/current/examples.src.protobuf.org.pantsbuild.example.service.service/current/org/pantsbuild/example/service
```
@@ -96,6 +96,7 @@
"test_suite": "dist/markdown/html/src/docs/common_tasks/test_suite.html",
"thrift_deps": "dist/markdown/html/examples/src/thrift/org/pantsbuild/example/README.html",
"thrift_gen": "dist/markdown/html/src/docs/common_tasks/thrift_gen.html",
"grpcio_gen": "dist/markdown/html/src/docs/common_tasks/python_proto_gen.html",
"tshoot": "dist/markdown/html/src/docs/tshoot.html",
"why_use_pants": "dist/markdown/html/src/docs/why_use_pants.html"
},
@@ -173,6 +174,7 @@
{"heading": "Code & Doc Generation"},
{"pages" : [
"thrift_deps",
"grpcio_gen",
"page"
]
},

0 comments on commit b2f5a49

Please sign in to comment.
You can’t perform that action at this time.