Implementing gRPC server using Python

By Martin Heinz

Martin Heinz

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

Original Photo by Zak Sakata on Unsplash

What is gRPC, Anyway?

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?

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.

Setting Up

Considering that we are using python to build our application, we will also need grpcio and grpcio-tools libraries:

Let’s Build Something

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:

In this 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 Reply.

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, --python-out and --grpc_python_out specify where to output generated *_pb2.py and *_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 PATH with -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 grpc and protobuf repositories and the easiest solution is to just fix those imports with sed.

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_server that 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 return with yield and return multiple responses (in for cycle).

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 make run.

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

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 ( make run):

We passed! Aaaand we are done!

Conclusion