gRPC-Python का इस्तेमाल शुरू करना

1. परिचय

इस कोडलैब में, gRPC-Python का इस्तेमाल करके एक क्लाइंट और सर्वर बनाया जाएगा. ये दोनों, Python में लिखे गए रूट-मैपिंग ऐप्लिकेशन की बुनियादी ज़रूरतें पूरी करते हैं.

ट्यूटोरियल के आखिर तक, आपके पास एक ऐसा क्लाइंट होगा जो gRPC का इस्तेमाल करके, रिमोट सर्वर से कनेक्ट होता है. इससे आपको मैप पर किसी खास जगह के नाम या पते की जानकारी मिलती है. कोई ऐप्लिकेशन, इस क्लाइंट-सर्वर डिज़ाइन का इस्तेमाल करके किसी रास्ते पर मौजूद लोकप्रिय जगहों की सूची बना सकता है या उनके बारे में खास जानकारी दे सकता है.

सेवा को प्रोटोकॉल बफ़र फ़ाइल में तय किया जाता है. इसका इस्तेमाल क्लाइंट और सर्वर के लिए बॉयलरप्लेट कोड जनरेट करने के लिए किया जाएगा, ताकि वे एक-दूसरे से कम्यूनिकेट कर सकें. इससे आपको इस सुविधा को लागू करने में समय और मेहनत नहीं करनी पड़ेगी.

जनरेट किया गया यह कोड, सर्वर और क्लाइंट के बीच कम्यूनिकेशन की जटिलताओं के साथ-साथ डेटा के क्रमबद्ध और क्रम से हटाने की प्रोसेस को भी मैनेज करता है.

आपको क्या सीखने को मिलेगा

• किसी सेवा के एपीआई को तय करने के लिए, प्रोटोकॉल बफ़र का इस्तेमाल कैसे करें.
• ऑटोमेटेड कोड जनरेशन का इस्तेमाल करके, प्रोटोकॉल बफ़र की परिभाषा से gRPC पर आधारित क्लाइंट और सर्वर बनाने का तरीका.
• gRPC के साथ क्लाइंट-सर्वर कम्यूनिकेशन के बारे में जानकारी.

यह कोडलैब, Python डेवलपर के लिए है. यह उन डेवलपर के लिए भी है जो gRPC का इस्तेमाल पहली बार कर रहे हैं या gRPC के बारे में फिर से जानकारी पाना चाहते हैं. इसके अलावा, यह उन लोगों के लिए भी है जो डिस्ट्रिब्यूटेड सिस्टम बनाने में दिलचस्पी रखते हैं. इसके लिए, gRPC का अनुभव होना ज़रूरी नहीं है.

2. शुरू करने से पहले

आपको किन चीज़ों की ज़रूरत होगी

• Python 3.9 या इसके बाद का वर्शन. हमारा सुझाव है कि Python 3.13 का इस्तेमाल करें. प्लैटफ़ॉर्म के हिसाब से इंस्टॉल करने के निर्देशों के लिए, Python Setup and Usage देखें. इसके अलावा, uv या pyenv जैसे टूल का इस्तेमाल करके, सिस्टम के बाहर से Python इंस्टॉल करें.
• Python पैकेज इंस्टॉल करने के लिए, pip का इस्तेमाल करें.
• Python वर्चुअल एनवायरमेंट बनाने के लिए, venv का इस्तेमाल करें.

ensurepip और venv पैकेज, Python स्टैंडर्ड लाइब्रेरी का हिस्सा हैं. ये आम तौर पर डिफ़ॉल्ट रूप से उपलब्ध होते हैं.

हालांकि, Debian पर आधारित कुछ डिस्ट्रिब्यूशन (जैसे, Ubuntu) Python को फिर से डिस्ट्रिब्यूट करते समय, इन्हें शामिल नहीं करते. पैकेज इंस्टॉल करने के लिए, यह कमांड चलाएं:

sudo apt install python3-pip python3-venv

कोड प्राप्त करें

इस कोडलैब में, पहले से बना सोर्स कोड स्केफ़ोल्ड उपलब्ध है. इससे आपको शुरुआत करने में मदद मिलेगी. यहां दिए गए तरीके से, आपको आवेदन पूरा करने में मदद मिलेगी. इसमें grpc_tools.protoc प्रोटोकॉल बफ़र कंपाइलर प्लगिन का इस्तेमाल करके, gRPC कोड जनरेट करना भी शामिल है.

grpc-codelabs

इस कोडलैब के लिए, स्कैफ़ोल्ड सोर्स कोड codelabs/grpc-python-getting-started/start_here डायरेक्ट्री में उपलब्ध है. अगर आपको कोड खुद लागू नहीं करना है, तो पूरा सोर्स कोड completed डायरेक्ट्री में उपलब्ध है.

सबसे पहले, कोडलैब की वर्किंग डायरेक्ट्री बनाएं और उसमें cd करें:

mkdir grpc-python-getting-started && cd grpc-python-getting-started

कोडलैब डाउनलोड करें और उसे एक्सट्रैक्ट करें:

curl -sL https://github.com/grpc-ecosystem/grpc-codelabs/archive/refs/heads/v1.tar.gz \
  | tar xvz --strip-components=4 \
  grpc-codelabs-1/codelabs/grpc-python-getting-started/start_here

इसके अलावा, सिर्फ़ कोडलैब डायरेक्ट्री वाली .zip फ़ाइल डाउनलोड करके, उसे मैन्युअल तरीके से अनज़िप किया जा सकता है.

ज़िप फ़ाइल डाउनलोड करें

3. सेवा के बारे में जानकारी देना

सबसे पहले, आपको प्रोटोकॉल बफ़र इंटरफ़ेस डेफ़िनिशन लैंग्वेज का इस्तेमाल करके, ऐप्लिकेशन की gRPC सेवा, उसके RPC तरीके, और उसके अनुरोध और जवाब के मैसेज टाइप तय करने होंगे. आपकी सेवा से ये सुविधाएं मिलेंगी:

• GetFeature नाम की एक आरपीसी विधि, जिसे सर्वर लागू करता है और क्लाइंट कॉल करता है.
• Point और Feature मैसेज टाइप, डेटा स्ट्रक्चर होते हैं. GetFeature तरीके का इस्तेमाल करते समय, क्लाइंट और सर्वर के बीच इनका आदान-प्रदान होता है. क्लाइंट, सर्वर को GetFeature अनुरोध में मैप के कोऑर्डिनेट Point के तौर पर देता है. इसके जवाब में सर्वर, उन कोऑर्डिनेट पर मौजूद जानकारी के साथ Feature भेजता है.

इस आरपीसी तरीके और इसके मैसेज टाइप को, दिए गए सोर्स कोड की protos/route_guide.proto फ़ाइल में तय किया जाएगा.

प्रोटोकॉल बफ़र को आम तौर पर प्रोटोबफ़ कहा जाता है. gRPC की शब्दावली के बारे में ज़्यादा जानने के लिए, gRPC के मुख्य कॉन्सेप्ट, आर्किटेक्चर, और लाइफ़साइकल देखें.

मैसेज के टाइप

सोर्स कोड की protos/route_guide.proto फ़ाइल में, सबसे पहले Point मैसेज टाइप तय करें. Point, मैप पर अक्षांश-देशांतर के निर्देशांकों के जोड़े को दिखाता है. इस कोडलैब के लिए, पूर्णांकों का इस्तेमाल करें:

message Point {
  int32 latitude = 1;
  int32 longitude = 2;
}

1 और 2 नंबर, message स्ट्रक्चर में मौजूद हर फ़ील्ड के लिए यूनीक आईडी नंबर होते हैं.

इसके बाद, Feature मैसेज टाइप तय करें. Feature, string फ़ील्ड का इस्तेमाल करता है. इससे Point में बताई गई जगह पर मौजूद किसी चीज़ का नाम या डाक पता पता चलता है:

message Feature {
  // The name or address of the feature.
  string name = 1;

  // The point where the feature is located.
  Point location = 2;
}

सेवा का तरीका

route_guide.proto फ़ाइल में service स्ट्रक्चर होता है, जिसका नाम RouteGuide होता है. यह ऐप्लिकेशन की सेवा के ज़रिए उपलब्ध कराए गए एक या उससे ज़्यादा तरीकों के बारे में बताता है.

RouteGuide डेफ़िनिशन में rpc तरीका GetFeature जोड़ें. जैसा कि पहले बताया गया है, यह तरीका निर्देशांकों के दिए गए सेट से किसी जगह का नाम या पता ढूंढता है. इसलिए, दिए गए Point के लिए GetFeature को Feature वैल्यू वापस करने के लिए कहें:

service RouteGuide {
  // Definition of the service goes here

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

यह एक यूनेरी आरपीसी तरीका है: एक सिंपल आरपीसी, जिसमें क्लाइंट सर्वर को अनुरोध भेजता है और जवाब मिलने का इंतज़ार करता है. यह लोकल फ़ंक्शन कॉल की तरह ही होता है.

4. क्लाइंट और सर्वर कोड जनरेट करना

इसके बाद, प्रोटोकॉल बफ़र कंपाइलर का इस्तेमाल करके, .proto फ़ाइल से क्लाइंट और सर्वर, दोनों के लिए बॉयलरप्लेट gRPC कोड जनरेट करें.

gRPC Python कोड जनरेट करने के लिए, हमने grpcio-tools बनाया है. इसमें ये चीज़ें शामिल हैं:

1. सामान्य protoc कंपाइलर, जो message की परिभाषाओं से Python कोड जनरेट करता है.
2. gRPC protobuf प्लगिन, जो service की परिभाषाओं से Python कोड (क्लाइंट और सर्वर स्टब) जनरेट करता है.

हम pip का इस्तेमाल करके, grpcio-tools Python पैकेज इंस्टॉल करेंगे. अपने प्रोजेक्ट की डिपेंडेंसी को सिस्टम पैकेज से अलग करने के लिए, चलिए एक नया Python वर्चुअल एनवायरमेंट (venv) बनाते हैं:

python3 -m venv --upgrade-deps .venv

bash/zsh शेल में वर्चुअल एनवायरमेंट चालू करने के लिए:

source .venv/bin/activate

Windows और नॉन-स्टैंडर्ड शेल के लिए, https://docs.python.org/3/library/venv.html#how-venvs-work पर मौजूद टेबल देखें.

ध्यान दें: हर बार नई शेल खोलने पर, आपको वर्चुअल एनवायरमेंट चालू करना होगा. activate स्क्रिप्ट, आपके $PATH वैरिएबल को कॉन्फ़िगर करती है, ताकि वह आपके venv से python और pip का इस्तेमाल कर सके. venv को बंद करने के लिए, बस deactivate चलाएं.

इसके बाद, grpcio-tools इंस्टॉल करें. इससे grpcio पैकेज भी इंस्टॉल हो जाता है:

pip install grpcio-tools

Python बॉयलरप्लेट कोड जनरेट करने के लिए, इस कमांड का इस्तेमाल करें:

python -m grpc_tools.protoc --proto_path=./protos  \
 --python_out=. --pyi_out=. --grpc_python_out=. \
 ./protos/route_guide.proto

इससे route_guide.proto में तय किए गए इंटरफ़ेस के लिए, ये फ़ाइलें जनरेट होंगी:

1. route_guide_pb2.py में ऐसा कोड होता है जो क्लास को डाइनैमिक तरीके से बनाता है. यह कोड, message की परिभाषाओं से जनरेट होता है.
2. route_guide_pb2.pyi, message की परिभाषाओं से जनरेट की गई "स्टब फ़ाइल" या "टाइप हिंट फ़ाइल" है. इसमें सिर्फ़ ऐसे हस्ताक्षर होते हैं जिन्हें लागू नहीं किया गया है. आईडीई, स्टब फ़ाइलों का इस्तेमाल करके, अपने-आप पूरा होने वाली सुविधा को बेहतर बना सकते हैं. साथ ही, गड़बड़ियों का पता लगा सकते हैं.
3. route_guide_pb2_grpc.py, service की परिभाषाओं से जनरेट होता है. इसमें gRPC से जुड़ी क्लास और फ़ंक्शन शामिल होते हैं.

तथ्य: _pb2 सफ़िक्स का मतलब proto2 सिंटैक्स नहीं है. इससे Python Protocol Buffers API के वर्शन के बारे में पता चलता है. फ़िलहाल, proto2, proto3, और Editions, जनरेट की गई फ़ाइलों के लिए _pb2.py का इस्तेमाल करते हैं.

gRPC के लिए खास तौर पर बनाए गए कोड में ये शामिल हैं:

1. RouteGuideStub, जिसका इस्तेमाल gRPC क्लाइंट, RouteGuide RPC को शुरू करने के लिए कर सकता है.
2. RouteGuideServicer, जो RouteGuide सेवा को लागू करने के लिए इंटरफ़ेस तय करता है.
3. add_RouteGuideServicer_to_server फ़ंक्शन का इस्तेमाल, RouteGuideServicer को gRPC सर्वर पर रजिस्टर करने के लिए किया जाता है.

5. सेवा बनाना

सबसे पहले, यह देखते हैं कि RouteGuide सर्वर कैसे बनाया जाता है. RouteGuide सर्वर बनाने और उसे चलाने के लिए, दो काम करने होते हैं:

• हमारी सेवा की परिभाषा से जनरेट किए गए सर्विसर इंटरफ़ेस को लागू करना. इसमें ऐसे फ़ंक्शन शामिल होते हैं जो सेवा का असल "काम" करते हैं.
• क्लाइंट से मिले अनुरोधों को सुनने और जवाब भेजने के लिए, किसी पोर्ट पर gRPC सर्वर चलाना.

आपको start_here/route_guide_server.py में, शुरुआती RouteGuide सर्वर मिल सकता है.

RouteGuide को लागू करना

route_guide_server.py में RouteGuideServicer क्लास है, जो जनरेट की गई क्लास route_guide_pb2_grpc.RouteGuideServicer की सबक्लास है:

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

RouteGuideServicer, RouteGuide सेवा के सभी तरीकों को लागू करता है.

आइए, आरपीसी को लागू करने के आसान तरीके के बारे में विस्तार से जानते हैं. GetFeature तरीके को क्लाइंट से Point मिलता है. इसके बाद, यह अपने डेटाबेस से Feature में मौजूद सुविधा की जानकारी दिखाता है.

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

इस तरीके में, आरपीसी के लिए route_guide_pb2.Point अनुरोध और grpc.ServicerContext ऑब्जेक्ट पास किया जाता है. यह ऑब्जेक्ट, आरपीसी से जुड़ी जानकारी देता है. जैसे, टाइम आउट की सीमाएं. यह route_guide_pb2.Feature जवाब देता है.

सर्वर शुरू करना

RouteGuide के सभी तरीकों को लागू करने के बाद, अगला चरण gRPC सर्वर शुरू करना है, ताकि क्लाइंट आपकी सेवा का इस्तेमाल कर सकें:

def serve():
    server = grpc.server(futures.ThreadPoolExecutor(max_workers=10))
    route_guide_pb2_grpc.add_RouteGuideServicer_to_server(
        RouteGuideServicer(),
        server,
    )
    listen_addr = "localhost:50051"
    server.add_insecure_port(listen_addr)
    print(f"Starting server on {listen_addr}")
    server.start()
    server.wait_for_termination()

सर्वर start() तरीका नॉन-ब्लॉकिंग है. अनुरोधों को मैनेज करने के लिए, एक नया थ्रेड इंस्टैंटिएट किया जाएगा. server.start() को कॉल करने वाले थ्रेड को अक्सर इस दौरान कोई और काम नहीं करना होता. इस मामले में, सर्वर बंद होने तक कॉल करने वाले थ्रेड को पूरी तरह से ब्लॉक करने के लिए, server.wait_for_termination() पर कॉल किया जा सकता है.

6. क्लाइंट बनाना

इस सेक्शन में, हम RouteGuide सेवा के लिए क्लाइंट बनाने का तरीका जानेंगे. start_here/route_guide_client.py में जाकर, शुरुआती क्लाइंट कोड देखा जा सकता है.

स्टब बनाना

सेवा के तरीकों को कॉल करने के लिए, हमें सबसे पहले एक स्टब बनाना होगा.

हम route_guide_pb2_grpc मॉड्यूल की RouteGuideStub क्लास को इंस्टैंशिएट करते हैं. यह क्लास, route_guide_client.py फ़ाइल में मौजूद हमारे .proto से जनरेट होती है.

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

सेवा के तरीकों को कॉल करना

एक रिस्पॉन्स देने वाले आरपीसी तरीकों के लिए, gRPC Python सिंक्रोनस (ब्लॉकिंग) और एसिंक्रोनस (नॉन-ब्लॉकिंग), दोनों तरह के कंट्रोल फ़्लो सिमैंटिक के साथ काम करता है. इन तरीकों को response-unary तरीके कहा जाता है.

सिंपल आरपीसी

सबसे पहले, हम सेवा को कॉल करने के लिए Point को तय करते हैं. यह route_guide_pb2 पैकेज से किसी ऑब्जेक्ट को कुछ प्रॉपर्टी के साथ इंस्टैंटिएट करने जितना आसान होना चाहिए:

point = route_guide_pb2.Point(latitude=412346009, longitude=-744026814)

सिंपल आरपीसी GetFeature को सिंक्रोनस कॉल करना, लोकल तरीके को कॉल करने जितना ही आसान है. आरपीसी कॉल, सर्वर से जवाब मिलने का इंतज़ार करता है. इसके बाद, यह या तो जवाब देता है या अपवाद दिखाता है. हम इस तरीके का इस्तेमाल करके, इस तरीके को कॉल कर सकते हैं और जवाब देख सकते हैं:

feature = stub.GetFeature(point)
print(feature)

आपके पास फ़ीचर ऑब्जेक्ट के फ़ील्ड की जांच करने और अनुरोध का नतीजा दिखाने का विकल्प होता है:

if feature.name:
    print(f"Feature called '{feature.name}' at {format_point(feature.location)}")
else:
    print(f"Found no feature at at {format_point(feature.location)}")

7. इसे आज़माएं

सर्वर चलाएं:

python route_guide_server.py

किसी दूसरे टर्मिनल से, वर्चुअल एनवायरमेंट को फिर से चालू करें. इसके बाद, क्लाइंट को चलाएं:

python route_guide_client.py

आपको इस तरह का आउटपुट दिखेगा. इसमें टाइमस्टैंप हटा दिए गए हैं, ताकि जानकारी साफ़ तौर पर दिख सके:

name: "16 Old Brook Lane, Warwick, NY 10990, USA"
location {
  latitude: 412346009
  longitude: -744026814
}

Feature called '16 Old Brook Lane, Warwick, NY 10990, USA' at latitude: 412346009, longitude: -744026814

8. आगे क्या करना है

• gRPC का परिचय और मुख्य सिद्धांत में, जानें कि gRPC कैसे काम करता है
• बुनियादी बातों वाला ट्यूटोरियल देखें
• Python API के बारे में जानकारी देखें