Nowadays, when people want to implement backend API, they go straight to creating applications with RESTful API that communicate using JSON, without even considering other options. In recent years though, gRPC and its protobufs started to get some traction and popularity thanks to many of their advantages. So, let’s see what’s all the buzz/hype about and implement gRPC server using Python!
TL;DR: Here is my repository with
grpc branch with all the sources from this article: https://github.com/MartinHeinz/python-project-blueprint/tree/grpc
What is gRPC, Anyway?
gRPC is Remote Procedure Call (RPC) protocol, that leverages Protocol Buffers (protobufs) as its message format. Using gRPC, the client application can directly call method available on a remote server using method stubs. It doesn’t matter in what language the server-side application is implemented as long as you have stubs (generated) for your client-side language. gRPC supports many languages, including Go, Java, Ruby, C# or our language of choice — Python. You can find more info in this overview.
Now, what are Protocol Buffers (protobufs)? Protobufs are alternative to formats like JSON or XML. They are a smaller, simpler and more efficient way of serializing data. To use protobufs, you need to define how you want the exchanged messages to look, for example (for more specifics see this language guide):
Aside from messages, we also need to define
services and their
rpc methods that will be implemented on server-side and called from client-side:
Why Should I Care, Anyway?
There are quite a few advantages to using gRPC over REST. First off, gRPC is much better when it comes to performance, thanks to the tight packing of protobufs, which reduces the size of payloads being sent. It also uses HTTP/2, instead of HTTP/1.1 as REST does. For these reasons, it’s a great choice for IoT, mobile devices or other constrained/low-power environments.
Another reason to choose gRPC over REST is that REST doesn’t mandate any real structure. You might define the format of requests and responses using OpenAPI, but that’s loose and optional. gRPC contracts, on the other hand, are stricter and clearly defined.
As already mentioned gRPC is using HTTP/2 and it’s good to mention that it’s taking full advantage of its features. To name a few: concurrent requests, streaming instead of request-response, smaller sensitivity to latency.
That said, there are also disadvantages and the biggest one being adoption. Not all clients (browsers) support the use of HTTP/2 making it problematic for external use. Considering performance advantages though, it’s clearly a great choice for internal services and communication, which you have control over.
To do anything with gRPC and protobufs, we need to install its compiler:
Considering that we are using python to build our application, we will also need
Let’s Build Something
With all tools ready we can now actually move onto building the application. For this example, I chose a simple echo server that sends you back your own messages.
The first thing we should talk about though is project layout. I chose the following directory/file structure:
This layout helps us clearly separate protobuf files (
.../proto), generated sources (
.../generated), actual source code and our test suite. To learn more about how to set up a Python project with this kind of layout you can check out my previous article:
So, to build the gRPC server, we — first and foremost — need to define messages and service(s) it will use you to communicate with clients:
echo.proto file we can see a very simple definition of message types - one for request (
EchoRequest) and one for reply (
EchoReply) from the server. These messages are then used by
Echo service, which consists of one RPC method called
To be able to use these definitions in Python code, we need to generate server and client interfaces. To do so, we can run this command:
We specified quite a few arguments. First of them —
-I blueprint/proto, tells
grpc_tools where to look for our
.proto files (it defines
PATH). Next two,
--grpc_python_out specify where to output generated
*_grpc_pb2.py files respectively. Last argument -
./blueprint/proto/*.proto is the actual path to
.proto files - this might seem like redundant as we specified
-I, but you need both to make this work.
When you run this one command however, you will end up with some broken imports in these generated files. There are multiple raised issues in
protobuf repositories and the easiest solution is to just fix those imports with
Writing this command out would not be very enjoyable nor efficient, so I wrapped it in
make target to make your (and mine) life easier. You can find complete
Makefile in my repository here.
There’s quite a bit of code that gets generated using this command, so I won’t go over every little bit, but there are a few important things to look out for. Each of these
*_pb2_grpc.py files has the following 3 things:
- Stub — First of them — Stub and in our case
EchoStub- is a class used by the client to connect to gRPC service
- Servicer — In our case
EchoServicer- is used by the server to implement the gRPC service
- Registration Function — Finally piece,
add_EchoServicer_to_serverthat is needed to register servicer with gRPC server.
So, let’s go over the code to see how to use this generated code.
The first thing we want to do is implement the actual service. We will do that in
grpc.py file, where we will keep all gRPC specific code:
Above, we create
Echoer class which inherits from generated
EchoServicer class, which contains all the methods defined in
.proto file. All these methods are intended to be overridden in our implementation and here we do just that. We implement the only method
Reply by returning
EchoReply message that we also previously defined in the
.proto file. I want to point out that the
request parameter here is an instance of
EchoReply - that's why we can get the
message out of it. We don't use the
context parameter here, but it contains some useful RPC-specific information, like timeout limits for example.
One neat feature I also want to mention is that in case you wanted to leverage the response-streaming you could replace
yield and return multiple responses (in
Now that we implemented the gRPC service, we want to run it. To do so, we need a server:
All this is, is just a single static method. It creates server from
grpc library with a few workers - in this case, 10. After that it uses previously mentioned registration function (
add_EchoServicer_to_server) to bind our
Echoer service to the server. Remaining 3 lines just add listening port, start the server and wait for interrupt.
All that remains for the server-side is
__main__.py, so that we can start it as Python module:
With that, we are all set to start the server. You can do that with
python -m blueprint or if you are using my template, then just
We have a server running, but we have no way of calling it… That’s where the client comes it. For demonstration purposes, we will create the client in Python using the stubs generated for us, but you could write the client in a completely different language.
For the client, we need only one function, which we call
run. After connecting the server, it creates stub that will allow us to call the server method, which is the next step. It calls
Reply method implemented on server-side by passing in
EchoRequest message with some payload. All that's left is to just print it.
Now, let’s run the client and see if everything works as expected:
And it does work!
Testing with Pytest
As with all my little projects and articles, we are not done until there are unit tests for all the code. To write sample test for this gRPC server, I will use Pytest and its plugin
Let’s first have a look at the fixtures used to simulate request-response exchange between client and server:
I think these are all pretty simple. Just make sure to use these specific names for these fixtures, as that’s what the plugin looks for. One thing to notice is the
grpc_channel argument in
grpc_stub. This is a fake channel supplied by
pytest-grpc plugin. For more info, I recommend going directly to
pytest-grpc source code, as the plugin is pretty simple. With that, let's move on to the actual test:
We create this test by leveraging
grpc_stub fixture which we wrote in the previous step. We create
EchoRequest which is passed to the
grpc_stub.Reply, followed by simple
assert. And, when we run the test (
We passed! Aaaand we are done!
If you take away just one thing from this article, then I think it should be the fact that we should always consider possible alternatives when deciding on solution/technology we want to use for some project. It doesn’t always need to be REST and JSON. Sometimes gRPC might fit the requirements way better. This kind of thinking also applies to any other technology or tool. To see full code listings with
Makefile automation, prepared Docker images and even set up for deployment to Kubernetes, please check out
grpc branch in my repository here: https://github.com/MartinHeinz/python-project-blueprint/tree/master. Any feedback is appreciated, as is star or fork in case you like this kind of content. 😉