Getting Started

Prerequisites

Before starting this assignment, ensure you have:

✅ Python 3.8 or higher installed
✅ pip package manager
✅ Basic understanding of Python programming
✅ Terminal/command line familiarity

Environment Setup

1. Create Project Directory

mkdir rpc-calculator
cd rpc-calculator

2. Create Virtual Environment

macOS/Linux:

python3 -m venv venv
source venv/bin/activate

Windows:

python -m venv venv
venv\Scripts\activate

3. Install Dependencies

Create requirements.txt:

grpcio==1.60.0
grpcio-tools==1.60.0
protobuf==4.25.1

Install packages:

pip install -r requirements.txt

Project Structure

Set up your project with this structure:

rpc-calculator/
├── proto/
│   └── calculator.proto          # Service definition
├── generated/                     # Auto-generated code (gitignore this)
│   ├── calculator_pb2.py
│   └── calculator_pb2_grpc.py
├── server.py                      # Server implementation
├── client.py                      # Client implementation
├── circuit_breaker.py            # Circuit breaker (Part 4)
├── tests/
│   ├── test_idempotency.py
│   └── test_circuit_breaker.py
├── requirements.txt
└── README.md

Quick Start Guide

Step 1: Download Starter Code

Proto File Provided

The calculator.proto file is provided as part of the assignment starter code. DO NOT create or modify this file. Download it from the course materials.

Download the starter code package which includes proto/calculator.proto:

syntax = "proto3";

package calculator;

service Calculator {
  rpc Add(BinaryOperation) returns (Result);
  rpc Subtract(BinaryOperation) returns (Result);
  rpc Multiply(BinaryOperation) returns (Result);
  rpc Divide(BinaryOperation) returns (Result);
}

message BinaryOperation {
  double a = 1;
  double b = 2;
}

message Result {
  double value = 1;
  string error = 2;
}

Step 2: Generate Python Code

python -m grpc_tools.protoc \
  -I./proto \
  --python_out=./generated \
  --grpc_python_out=./generated \
  ./proto/calculator.proto

This creates: - calculator_pb2.py - Message classes - calculator_pb2_grpc.py - Service classes

Step 3: Implement Server

Create server.py:

import grpc
from concurrent import futures
import sys
sys.path.append('./generated')
import calculator_pb2
import calculator_pb2_grpc

class CalculatorServicer(calculator_pb2_grpc.CalculatorServicer):
    def Add(self, request, context):
        # TODO: Implement addition logic
        # Hint: Access operands via request.a and request.b
        # Return calculator_pb2.Result(value=...)
        pass

def serve():
    server = grpc.server(futures.ThreadPoolExecutor(max_workers=10))
    calculator_pb2_grpc.add_CalculatorServicer_to_server(
        CalculatorServicer(), server
    )
    server.add_insecure_port('[::]:50051')
    print("Server starting on port 50051...")
    server.start()
    server.wait_for_termination()

if __name__ == '__main__':
    serve()

Step 4: Implement Client

Create client.py:

import grpc
import sys
sys.path.append('./generated')
import calculator_pb2
import calculator_pb2_grpc

def run():
    # TODO: Create insecure channel to 'localhost:50051'
    # TODO: Create CalculatorStub from channel
    # TODO: Call stub.Add with BinaryOperation(a=10, b=5)
    # TODO: Print the result
    pass

if __name__ == '__main__':
    run()

Step 5: Run the Application

Terminal 1 - Start Server:

python server.py

Terminal 2 - Run Client:

python client.py

Expected output (after you implement the TODOs):

10 + 5 = 15.0

Verification Checklist

✅ Python 3.8+ installed (python --version)
✅ Virtual environment activated
✅ Dependencies installed (pip list | grep grpc)
✅ Proto file compiles without errors
✅ Server starts successfully
✅ Client can connect and receive responses

Common Issues

Issue: "No module named 'calculator_pb2'"

Solution: Make sure you generated the Python code:

python -m grpc_tools.protoc -I./proto --python_out=./generated --grpc_python_out=./generated ./proto/calculator.proto

And added the generated folder to your path:

sys.path.append('./generated')

Issue: "failed to connect to all addresses"

Solution: 1. Check if server is running 2. Verify port number matches (50051) 3. Try localhost instead of 127.0.0.1 or vice versa

Issue: Import errors for generated files

Solution: Use absolute imports or fix the path:

import sys
import os
sys.path.insert(0, os.path.join(os.path.dirname(__file__), 'generated'))

Next Steps

Now that your environment is set up:

✅ Complete Part 1: Basic RPC
Review gRPC Setup Guide for detailed configuration
Check Code Examples for reference implementations