Python Generated Code Reference

Introduction

gRPC Python relies on the protocol buffers compiler (protoc) to generatecode. It uses a plugin to supplement the generated code by plain protocwith gRPC-specific code. For a .proto service description containinggRPC services, the plain protoc generated code is synthesized ina _pb2.py file, and the gRPC-specifc code lands in a _grpc_pb2.py file.The latter python module imports the former. In this guide, we focuson the gRPC-specific subset of the generated code.

Illustrative Example

Let’s look at the following FortuneTeller proto service:

service FortuneTeller {
  // Returns the horoscope and zodiac sign for the given month and day.
  rpc TellFortune(HoroscopeRequest) returns (HoroscopeResponse) {
    // errors: invalid month or day, fortune unavailable
  }
  // Replaces the fortune for the given zodiac sign with the provided one.
  rpc SuggestFortune(SuggestionRequest) returns (SuggestionResponse) {
    // errors: invalid zodiac sign
  }
}

gRPC protoc plugin will synthesize code elements along the linesof what follows in the corresponding _pb2_grpc.py file:

import grpc
import fortune_pb2
class FortuneTellerStub(object):
  def __init__(self, channel):
    """Constructor.
    Args:
      channel: A grpc.Channel.
    """
    self.TellFortune = channel.unary_unary(
        '/example.FortuneTeller/TellFortune',
        request_serializer=fortune_pb2.HoroscopeRequest.SerializeToString,
        response_deserializer=fortune_pb2.HoroscopeResponse.FromString,
        )
    self.SuggestFortune = channel.unary_unary(
        '/example.FortuneTeller/SuggestFortune',
        request_serializer=fortune_pb2.SuggestionRequest.SerializeToString,
        response_deserializer=fortune_pb2.SuggestionResponse.FromString,
        )
class FortuneTellerServicer(object):
  def TellFortune(self, request, context):
    """Returns the horoscope and zodiac sign for the given month and day.
    errors: invalid month or day, fortune unavailable
    """
    context.set_code(grpc.StatusCode.UNIMPLEMENTED)
    context.set_details('Method not implemented!')
    raise NotImplementedError('Method not implemented!')
  def SuggestFortune(self, request, context):
    """Replaces the fortune for the given zodiac sign with the provided
one.
    errors: invalid zodiac sign
    """
    context.set_code(grpc.StatusCode.UNIMPLEMENTED)
    context.set_details('Method not implemented!')
    raise NotImplementedError('Method not implemented!')
def add_FortuneTellerServicer_to_server(servicer, server):
  rpc_method_handlers = {
      'TellFortune': grpc.unary_unary_rpc_method_handler(
          servicer.TellFortune,
          request_deserializer=fortune_pb2.HoroscopeRequest.FromString,
          response_serializer=fortune_pb2.HoroscopeResponse.SerializeToString,
      ),
      'SuggestFortune': grpc.unary_unary_rpc_method_handler(
          servicer.SuggestFortune,
          request_deserializer=fortune_pb2.SuggestionRequest.FromString,
          response_serializer=fortune_pb2.SuggestionResponse.SerializeToString,
      ),
  }
  generic_handler = grpc.method_handlers_generic_handler(
      'example.FortuneTeller', rpc_method_handlers)
  server.add_generic_rpc_handlers((generic_handler,))

Code Elements

The gRPC generated code starts by importing the grpc package and the plain_pb2 module, synthesized by protoc, which defines non-gRPC-specifc codeelements, like the classes corresponding to protocol buffers messages anddescriptors used by reflection.

For each service Foo in the .proto file, three primary elements aregenerated:

• Stub: FooStub used by the client to connect to a gRPC service.
• Servicer: FooServicer used by the server to implement agRPC service.
• Registration Function:add_FooServicer_to_server function used to register a servicer with agrpc.Server object.

Stub

The generated Stub class is used by the gRPC clients. Itwill have a constructor that takes a grpc.Channel object and initializes thestub. For each method in the service, the initializer adds a correspondingattribute to the stub object with the same name. Depending on the RPC type(i.e. unary or streaming), the value of that attribute will be callableobjects of typeUnaryUnaryMultiCallable,UnaryStreamMultiCallable,StreamUnaryMultiCallable,orStreamStreamMultiCallable.

Servicer

For each service, a Servicer class is generated. Thisclass is intended to serve as the superclass of a service implementation. Foreach method in the service, a corresponding function in the Servicer classwill be synthesized which is intended to be overriden in the actual serviceimplementation. Comments associated with code elementsin the .proto file will be transferred over as docstrings inthe generated python code.

Registration Function

For each service, a function will begenerated that registers a Servicer object implementing it on a grpc.Serverobject, so that the server would be able to appropriately route the queries tothe respective servicer. This function takes an object that implements theServicer, typically an instance of a subclass of the generated Servicercode element described above, and agrpc.Serverobject.