Beta Python documentation correction and update

pythias · Sep 10, 2015 · 061d288 · 061d288
1 parent f65d3c1
commit 061d288
Show file tree

Hide file tree

Showing 8 changed files with 230 additions and 120 deletions.
diff --git a/examples/python/helloworld/README.md b/examples/python/helloworld/README.md
@@ -91,9 +91,6 @@ Which internally invokes the proto-compiler as:
 $ protoc -I ../../protos --python_out=. --grpc_out=. --plugin=protoc-gen-grpc=`which grpc_python_plugin` ../../protos/helloworld.proto
 ```
 
-Optionally, you can just skip the code generation step as the generated python module has already
-been generated for you (helloworld_pb2.py).
-
 ### The client
 
 Client-side code can be found in [greeter_client.py](greeter_client.py).

diff --git a/examples/python/helloworld/greeter_client.py b/examples/python/helloworld/greeter_client.py
@@ -29,15 +29,18 @@
 
 """The Python implementation of the GRPC helloworld.Greeter client."""
 
+from grpc.beta import implementations
+
 import helloworld_pb2
 
 _TIMEOUT_SECONDS = 10
 
 
 def run():
-  with helloworld_pb2.early_adopter_create_Greeter_stub('localhost', 50051) as stub:
-    response = stub.SayHello(helloworld_pb2.HelloRequest(name='you'), _TIMEOUT_SECONDS)
-    print "Greeter client received: " + response.message
+  channel = implementations.insecure_channel('localhost', 50051)
+  stub = helloworld_pb2.beta_create_Greeter_stub(channel)
+  response = stub.SayHello(helloworld_pb2.HelloRequest(name='you'), _TIMEOUT_SECONDS)
+  print "Greeter client received: " + response.message
 
 
 if __name__ == '__main__':

diff --git a/examples/python/helloworld/greeter_server.py b/examples/python/helloworld/greeter_server.py
@@ -36,15 +36,15 @@
 _ONE_DAY_IN_SECONDS = 60 * 60 * 24
 
 
-class Greeter(helloworld_pb2.EarlyAdopterGreeterServicer):
+class Greeter(helloworld_pb2.BetaGreeterServicer):
 
   def SayHello(self, request, context):
     return helloworld_pb2.HelloReply(message='Hello, %s!' % request.name)
 
 
 def serve():
-  server = helloworld_pb2.early_adopter_create_Greeter_server(
-      Greeter(), 50051, None, None)
+  server = helloworld_pb2.beta_create_Greeter_server(Greeter())
+  server.add_insecure_port('[::]:50051')
   server.start()
   try:
     while True:

diff --git a/examples/python/route_guide/README.md b/examples/python/route_guide/README.md
@@ -29,7 +29,7 @@ Then change your current directory to `examples/python/route_guide`:
 $ cd examples/python/route_guide
 ```
 
-You also should have the relevant tools installed to generate the server and client interface code - if you don't already, follow the setup instructions in [the Python quick start guide](../python).
+You also should have the relevant tools installed to generate the server and client interface code - if you don't already, follow the setup instructions in [the Python quick start guide](../helloworld).
 
 ## Defining the service
 
@@ -99,12 +99,11 @@ $ protoc -I ../../protos --python_out=. --grpc_out=. --plugin=protoc-gen-grpc=`w
 Note that as we've already provided a version of the generated code in the example repository, running this command regenerates the appropriate file rather than creates a new one. The generated code file is called `route_guide_pb2.py` and contains:
 - classes for the messages defined in route_guide.proto
 - abstract classes for the service defined in route_guide.proto
-   - `EarlyAdopterRouteGuideServicer`, which defines the interface for implementations of the RouteGuide service
-   - `EarlyAdopterRouteGuideServer`, which may be started and stopped
-   - `EarlyAdopterRouteGuideStub`, which can be used by clients to invoke RouteGuide RPCs
+   - `BetaRouteGuideServicer`, which defines the interface for implementations of the RouteGuide service
+   - `BetaRouteGuideStub`, which can be used by clients to invoke RouteGuide RPCs
 - functions for application use
-   - `early_adopter_create_RouteGuide_server`, which creates a gRPC server given an `EarlyAdopterRouteGuideServicer` object
-   - `early_adopter_create_RouteGuide_stub`, which can be used by clients to create a stub object
+   - `beta_create_RouteGuide_server`, which creates a gRPC server given a `BetaRouteGuideServicer` object
+   - `beta_create_RouteGuide_stub`, which can be used by clients to create a stub object
 
 <a name="server"></a>
 ## Creating the server
@@ -119,11 +118,11 @@ You can find the example `RouteGuide` server in [route_guide_server.py](route_gu
 
 ### Implementing RouteGuide
 
-`route_guide_server.py` has a `RouteGuideServicer` class that implements the generated interface `route_guide_pb2.EarlyAdopterRouteGuideServicer`:
+`route_guide_server.py` has a `RouteGuideServicer` class that implements the generated interface `route_guide_pb2.BetaRouteGuideServicer`:
 
 ```python
 # RouteGuideServicer provides an implementation of the methods of the RouteGuide service.
-class RouteGuideServicer(route_guide_pb2.EarlyAdopterRouteGuideServicer):
+class RouteGuideServicer(route_guide_pb2.BetaRouteGuideServicer):
 ```
 
 `RouteGuideServicer` implements all the `RouteGuide` service methods.
@@ -141,7 +140,7 @@ Let's look at the simplest type first, `GetFeature`, which just gets a `Point` f
       return feature
 ```
 
-The method is passed a `route_guide_pb2.Point` request for the RPC, and an `RpcContext` object that provides RPC-specific information such as timeout limits. It returns a `route_guide_pb2.Feature` response.
+The method is passed a `route_guide_pb2.Point` request for the RPC, and a `ServicerContext` object that provides RPC-specific information such as timeout limits. It returns a `route_guide_pb2.Feature` response.
 
 #### Response-streaming RPC
 
@@ -212,8 +211,8 @@ Once you have implemented all the `RouteGuide` methods, the next step is to star
 
 ```python
 def serve():
-  server = route_guide_pb2.early_adopter_create_RouteGuide_server(
-      RouteGuideServicer(), 50051, None, None)
+  server = route_guide_pb2.beta_create_RouteGuide_server(RouteGuideServicer())
+  server.add_insecure_port('[::]:50051')
   server.start()
 ```
 
@@ -228,17 +227,14 @@ You can see the complete example client code in [route_guide_client.py](route_gu
 
 To call service methods, we first need to create a *stub*.
 
-We use the `early_adopter_create_RouteGuide_stub` function of the `route_guide_pb2` module, generated from our .proto.
+We use the `beta_create_RouteGuide_stub` function of the `route_guide_pb2` module, generated from our .proto.
 
 ```python
-stub = RouteGuide::Stub.new('localhost', 50051)
+channel = implementations.insecure_channel('localhost', 50051)
+stub = beta_create_RouteGuide_stub(channel)
 ```
 
-The returned object implements all the methods defined by the `EarlyAdopterRouteGuideStub` interface, and is also a [context manager](https://docs.python.org/2/library/stdtypes.html#typecontextmanager). All RPCs invoked on the stub must be invoked within the stub's context, so it is common for stubs to be created and used with a [with statement](https://docs.python.org/2/reference/compound_stmts.html#the-with-statement):
-
-```python
-with route_guide_pb2.early_adopter_create_RouteGuide_stub('localhost', 50051) as stub:
-```
+The returned object implements all the methods defined by the `BetaRouteGuideStub` interface.
 
 ### Calling service methods
 
@@ -255,7 +251,7 @@ feature = stub.GetFeature(point, timeout_in_seconds)
 An asynchronous call to `GetFeature` is similar, but like calling a local method asynchronously in a thread pool:
 
 ```python
-feature_future = stub.GetFeature.async(point, timeout_in_seconds)
+feature_future = stub.GetFeature.future(point, timeout_in_seconds)
 feature = feature_future.result()
 ```
 
@@ -276,7 +272,7 @@ route_summary = stub.RecordRoute(point_sequence, timeout_in_seconds)
 ```
 
 ```python
-route_summary_future = stub.RecordRoute.async(point_sequence, timeout_in_seconds)
+route_summary_future = stub.RecordRoute.future(point_sequence, timeout_in_seconds)
 route_summary = route_summary_future.result()
 ```
 

diff --git a/examples/python/route_guide/route_guide_client.py b/examples/python/route_guide/route_guide_client.py
@@ -32,6 +32,8 @@
 import random
 import time
 
+from grpc.beta import implementations
+
 import route_guide_pb2
 import route_guide_resources
 
@@ -115,15 +117,16 @@ def guide_route_chat(stub):
 
 
 def run():
-  with route_guide_pb2.early_adopter_create_RouteGuide_stub('localhost', 50051) as stub:
-    print "-------------- GetFeature --------------"
-    guide_get_feature(stub)
-    print "-------------- ListFeatures --------------"
-    guide_list_features(stub)
-    print "-------------- RecordRoute --------------"
-    guide_record_route(stub)
-    print "-------------- RouteChat --------------"
-    guide_route_chat(stub)
+  channel = implementations.insecure_channel('localhost', 50051)
+  stub = route_guide_pb2.beta_create_RouteGuide_stub(channel)
+  print "-------------- GetFeature --------------"
+  guide_get_feature(stub)
+  print "-------------- ListFeatures --------------"
+  guide_list_features(stub)
+  print "-------------- RecordRoute --------------"
+  guide_record_route(stub)
+  print "-------------- RouteChat --------------"
+  guide_route_chat(stub)
 
 
 if __name__ == '__main__':