Introduction to the basic tutorial of GRPC in Python.

This tutorial provides a basic introduction to Python programmer using GRPC.

By browsing this example, how will you learn:

Define services in the .proto file.
Use the protocol buffer compiler to generate server and client code.
Use the Python GRPC API to write a simple client and server for your service.
It is assumed that you have read the GRPC profile and are familiar with the protocol buffer. You can find more information and the code guide generated by Python in the Proto3 language guide.

Why use GRPC?

Our example is a simple route mapping application that allows the client to obtain information about the characteristics on its route, create routes, and exchange route information with the server and other clients, such as traffic updates.

Using GRPC, we can define our services in a .proto file, and generate clients and servers with any language supported by GRPC. These clients and servers can be in the servers from large data centers to your own tablet Operation in the environment of the computer -the complex of all communication GRPCs handle different languages ​​and environments for you. We also obtained all the advantages of using the protocol buffer, including efficient serialization, simple IDL and relaxed interface updates.

Example code and settings

The example code of this tutorial is located in GRPC/GRPC/EXAMPLES/Python/Route_guide. GRPC to download the example.

$ git clone -b v1.46.3 --depth 1 --shallow-submodules https://github.com/grpc/grpc

Then change the current directory to Examples/Python/Route_guide as the repository:

$ cd grpc/examples/python/route_guide

You should also install related tools to generate the server and client interface code -if you do not have it yet, please follow the setting instructions in the fast entry.

Define service

Your first step (as you know from GRPC) uses the protocol buffer to define the GRPC service and method request and response type. You can see the complete .proto file Examples/Protos/Route_guide.proto.

To define the service, please specify a name in the .proto file:

service RouteGuide {
   // (Method definitions not shown)
}

The RPC then defines the method in the service definition, specifying their requests and response types. GRPC allows you to define four service methods. All these methods are used in the Routeguide service:

A simple RPC, where the client sends a request to the server and waits for the response to return, just like a normal function call.

// Obtains the feature at a given position.
rpc GetFeature(Point) returns (Feature) {}

A response stream RPC, where the client sends a request to the server and obtains a stream to read a series of messages. The client reads from the return stream until there is no more news. As you can see in an example, you specify the response flow method by putting the Stream keyword before the response type.

// Obtains the Features available within the given Rectangle.  Results are
// streamed rather than returned at once (e.g. in a response message with a
// repeated field), as the rectangle may cover a large area and contain a
// huge number of features.
rpc ListFeatures(Rectangle) returns (stream Feature) {}

A request stream RPC, wherein the client is written into a series of messages and sent them to the server, and the stream provided again. Once the client completes the message, it will wait for the server to read all messages and return its response. You can specify the request flow method by putting the Stream keyword in the request type.

// Accepts a stream of Points on a route being traversed, returning a
// RouteSummary when traversal is completed.
rpc RecordRoute(stream Point) returns (RouteSummary) {}

In the two -way streaming RPC, the two sides use read and write streams to send a series of messages. These two streams are operating independently, so the client and server can read and write in any order they like: for example, the server can wait for all client messages before writing to response, or it can read the message alternately and write the message and write it. Enter the message, or other combinations of reading and writing. Keep the order of the message in each stream. Stream you can specify this type of method by putting keywords before requests and responses.

// Accepts a stream of RouteNotes sent while a route is being traversed,
// while receiving other RouteNotes (e.g. from other users).
rpc RouteChat(stream RouteNote) returns (stream RouteNote) {}

Your .proto file also included all requests and response type protocol buffer message type definitions of all requests and response types used in our service methods -For example, this is the Point message type:

// Points are represented as latitude-longitude pairs in the E7 representation
// (degrees multiplied by 10**7 and rounded to the nearest integer).
// Latitudes should be in the range +/- 90 degrees and longitude should be in
// the range +/- 180 degrees (inclusive).
message Point {
  int32 latitude = 1;
  int32 longitude = 2;
}

Generate client and server code

Next, you need to generate GRPC clients and server interfaces from the .proto service definition.

First, install GRPCIO-TOOLS package:

$ pip install grpcio-tools

Use the following command to generate the Python code:

$ python -m grpc_tools.protoc -I../../protos --python_out=. --grpc_python_out=. ../../protos/route_guide.proto

Please note that since we have provided a version of generating code in the sample directory, it will re -generate an appropriate file in running this command instead of creating a new file. The generated code file is called route_guide_pb2.py and route_guide_pb2_grpc.py includes:

Class of messages defined in route_guide.proto
Category of services defined in route_guide.proto
RouteguideStub, the client can use it to call Routeguide RPC
RouteguideServiceer, which defines the interface of the Routeguide service implementation
The function of the service defined in Route_guide.proto
add_routeguideServicer_to_Server, it adds routeguideServicer to grpc.server
notes
The produced code in PB22 follows the Protocol Buffers Python API version 2. Version 1 is out of date. It has nothing to do with the protocol buffer language version, and the language version of the protocol buffer area is indicated by the .proto file indicator syntax = "Proto3" or Syntax = "Proto2" in the .proto file.

Create a server

First let's see how to create the Routeguide server. If you are only interested in creating a GRPC client, you can skip this section and enter the client directly (although you may think it is interesting!).

Create and run the Routeguide server are divided into two working items:

Use the function of "work" to implement the service program interface generated from our service definition.
Run the GRPC server to listen to requests from the client and transmit response.
You can find the example server in Examples/Python/Route_guide/Route_server.pyrouteguide.

Implementation route guide

Route_guide_server.py has a routeguideServicer subclass generated by route_guide_pb2_grpc.routeguideServicer:

# RouteGuideServicer provides an implementation of the methods of the RouteGuide service.
class RouteGuideServicer(route_guide_pb2_grpc.RouteGuideServicer):

RouteguideServicer implements all Routeguide service methods.

Simple RPC

Let's look at the simplest type GetFeature first. It is just Point obtaining A from the client and returning the corresponding feature information Feature from its database in A.

def GetFeature(self, request, context):
  feature = get_feature(self.db, request)
  if feature is None:
    return route_guide_pb2.Feature(name="", location=request)
  else:
    return feature

This method is conveyed a RPC request for RPC, and a GRPC.ServicerContext object that provides RPC specific information (such as timeout limit). It returns a route_guide_pb2.feature response.

Response flow RPC
Let's take a look at the next method now. ListFeatures is a response stream RPC that sends multiple features to the client.

def ListFeatures(self, request, context):
  left = min(request.lo.longitude, request.hi.longitude)
  right = max(request.lo.longitude, request.hi.longitude)
  top = max(request.lo.latitude, request.hi.latitude)
  bottom = min(request.lo.latitude, request.hi.latitude)
  for feature in self.db:
    if (feature.location.longitude >= left and
        feature.location.longitude <= right and
        feature.location.latitude >= bottom and
        feature.location.latitude <= top):
      yield feature

The request message here is the news that Route_guide_PB2.RECTANGLE client wants to find Features in it. This method does not return a single response, but to produce zero or multiple responses.

Request stream RPC
The Request-Streaming method Recordroute uses an iterative request value and returns a single response value.

def RecordRoute(self, request_iterator, context):
  point_count = 0
  feature_count = 0
  distance = 0.0
  prev_point = None

  start_time = time.time()
  for point in request_iterator:
    point_count += 1
    if get_feature(self.db, point):
      feature_count += 1
    if prev_point:
      distance += get_distance(prev_point, point)
    prev_point = point

  elapsed_time = time.time() - start_time
  return route_guide_pb2.RouteSummary(point_count=point_count,
                                      feature_count=feature_count,
                                      distance=int(distance),
                                      elapsed_time=int(elapsed_time))

Two -way streaming RPC
Finally, let's take a look at the two -way flow method Routechat.

def RouteChat(self, request_iterator, context):
  prev_notes = []
  for new_note in request_iterator:
    for prev_note in prev_notes:
      if prev_note.location == new_note.location:
        yield prev_note
    prev_notes.append(new_note)

The semantics of this method is a combination of request flow method and response flow method. It is transmitted to a request value, it is an iterator of the response value itself.

Start the server
After implementing all the ROUTEGUIDE methods, the next step is to start the GRPC server so that the client can actually use your service:

def serve():
  server = grpc.server(futures.ThreadPoolExecutor(max_workers=10))
  route_guide_pb2_grpc.add_RouteGuideServicer_to_server(
      RouteGuideServicer(), server)
  server.add_insecure_port('[::]:50051')
  server.start()
  server.wait_for_termination()

The server start () method is non -blocking. Examine a new thread to process the request. During this period, the thread call server.start () usually does not have any other jobs to do. In this case, you can call the server.wait_For_Termination () to block the calling thread cleanly until the server is terminated.

Create a client
You can see a complete example client code in Examples/Python/Route_guide/Route_guide_client.py.

Create a tray root
To call the service method, we first need to create a deposit.

We instantiated the module class to generate Routeguidestub from .proto. route_guide_pb2_grpc

channel = grpc.insecure_channel('localhost:50051')
stub = route_guide_pb2_grpc.RouteGuideStub(channel)

Call service method
For the RPC method ("response one yuan" method) to return a single response, GRPC Python supports synchronization (blocking) and asynchronous (non -blocking) control semantics. For the response flow RPC method, the call will return to the iterator of the response value immediately. The next () method of the iterator is observed until the response generated from the iterative device is changed to available.

Simple RPC
The simplicity of the simplicity RPC call getFeature is almost as simple as calling the local method. RPC calls waiting for server response, and will return response or cause abnormalities:

feature = stub.GetFeature(point)

Asynchronous calls are similar to that of getFeature, but similar to the asynchronous calling local method in the thread pool:

feature_future = stub.GetFeature.future(point)
feature = feature_future.result()

Response flow RPC
Call response-streamingListFeatures Similar to the sequence type:

for feature in stub.ListFeatures(rectangle):

Request stream RPC
Calling the request stream ReCordRoute is similar to passing the iterator to the local method. Just like the simple RPC of a single response above, it can be synchronized or asynchronous calls:

route_summary = stub.RecordRoute(point_iterator)
route_summary_future = stub.RecordRoute.future(point_iterator)
route_summary = route_summary_future.result()

Two -way streaming RPC
Call the two -way streaming transmission Routechat to have a combination of stream transmission and response flow transmission semantics:

for received_route_note in stub.RouteChat(sent_route_note_iterator):

Try it!
Run the server:

$ python route_guide_server.py

Run the client from different terminals:

$ python route_guide_client.py