Quick start

Prerequisites

• Python 3.7 or higher
• pip version 9.0.1 or higher

If necessary, upgrade your version ofpip:

python -m pip install --upgrade pip

If you cannot upgradepip due to a system-owned installation, you canrun the example in a virtualenv:

python -m pip install virtualenvvirtualenv venvsource venv/bin/activatepython -m pip install --upgrade pip

gRPC

Install gRPC:

python -m pip install grpcio

Or, to install it system wide:

sudo python -m pip install grpcio

gRPC tools

Python’s gRPC tools include the protocol buffer compilerprotoc and thespecial plugin for generating server and client code from.proto servicedefinitions. For the first part of our quick-start example, we’ve alreadygenerated the server and client stubs fromhelloworld.proto,but you’ll need the tools for the rest of our quick start, as well as latertutorials and your own projects.

To install gRPC tools, run:

python -m pip install grpcio-tools

Download the example

You’ll need a local copy of the example code to work through this quick start.Download the example code from our GitHub repository (the following commandclones the entire repository, but you just need the examples for this quick startand other tutorials):

# Clone the repository to get the example code:git clone -b v1.76.0 --depth1 --shallow-submodules https://github.com/grpc/grpc# Navigate to the "hello, world" Python example:cd grpc/examples/python/helloworld

Run a gRPC application

From theexamples/python/helloworld directory:

1. Run the server:

   python greeter_server.py

2. From another terminal, run the client:

   python greeter_client.py

Congratulations! You’ve just run a client-server application with gRPC.

Update the gRPC service

Now let’s look at how to update the application with an extra method on theserver for the client to call. Our gRPC service is defined using protocolbuffers; you can find out lots more about how to define a service in a.protofile inIntroduction to gRPC andBasics tutorial. For now all you needto know is that both the server and the client “stub” have aSayHello RPCmethod that takes aHelloRequest parameter from the client and returns aHelloReply from the server, and that this method is defined like this:

// The greeting service definition.service Greeter {// Sends a greetingrpc SayHello (HelloRequest)returns (HelloReply) {}}// The request message containing the user's name.messageHelloRequest {string name=1;}// The response message containing the greetingsmessageHelloReply {stringmessage=1;}

Let’s update this so that theGreeter service has two methods. Editexamples/protos/helloworld.proto and update it with a newSayHelloAgainmethod, with the same request and response types:

// The greeting service definition.service Greeter {// Sends a greetingrpc SayHello (HelloRequest)returns (HelloReply) {}// Sends another greetingrpc SayHelloAgain (HelloRequest)returns (HelloReply) {}}// The request message containing the user's name.messageHelloRequest {string name=1;}// The response message containing the greetingsmessageHelloReply {stringmessage=1;}

Remember to save the file!

Generate gRPC code

Next we need to update the gRPC code used by our application to use the newservice definition.

From theexamples/python/helloworld directory, run:

python -m grpc_tools.protoc -I../../protos --python_out=. --pyi_out=. --grpc_python_out=. ../../protos/helloworld.proto

This regenerateshelloworld_pb2.py which contains our generated request andresponse classes andhelloworld_pb2_grpc.py which contains our generatedclient and server classes.

Update and run the application

We now have new generated server and client code, but we still need to implementand call the new method in the human-written parts of our example application.

Update the server

In the same directory, opengreeter_server.py. Implement the new method likethis:

classGreeter(helloworld_pb2_grpc.GreeterServicer):defSayHello(self, request, context):return helloworld_pb2.HelloReply(message=f"Hello,{request.name}!")defSayHelloAgain(self, request, context):return helloworld_pb2.HelloReply(message=f"Hello again,{request.name}!")...

Update the client

In the same directory, opengreeter_client.py. Call the new method like this:

defrun():with grpc.insecure_channel('localhost:50051')as channel:        stub= helloworld_pb2_grpc.GreeterStub(channel)        response= stub.SayHello(helloworld_pb2.HelloRequest(name='you'))print("Greeter client received: "+ response.message)        response= stub.SayHelloAgain(helloworld_pb2.HelloRequest(name='you'))print("Greeter client received: "+ response.message)

Run!

Just like we did before, from theexamples/python/helloworld directory:

1. Run the server:

   python greeter_server.py

2. From another terminal, run the client:

   python greeter_client.py

What’s next

• Learn how gRPC works inIntroduction to gRPCandCore concepts.
• Work through theBasics tutorial.
• Explore theAPI reference.