From 98ea67a5942d097fe7ea8e71ea9ce61301523077 Mon Sep 17 00:00:00 2001
From: Tianzi Cai <tianzi@google.com>
Date: Tue, 15 Dec 2020 16:40:22 -0800
Subject: [PATCH] docs: update samples in documentation

---
 README.rst                | 12 +++++++-----
 docs/publisher/index.rst  |  4 ++--
 docs/subscriber/index.rst | 20 ++++++++++++++++----
 3 files changed, 25 insertions(+), 11 deletions(-)

diff --git a/README.rst b/README.rst
index 926e51f1e..9db987f2e 100644
--- a/README.rst
+++ b/README.rst
@@ -111,7 +111,8 @@ messages to it
         topic='MY_TOPIC_NAME',  # Set this to something appropriate.
     )
     publisher.create_topic(topic_name)
-    publisher.publish(topic_name, b'My first message!', spam='eggs')
+    future = publisher.publish(topic_name, b'My first message!', spam='eggs')
+    future.result()
 
 To learn more, consult the `publishing documentation`_.
 
@@ -129,23 +130,24 @@ the topic, and subscribe to that, passing a callback function.
     import os
     from google.cloud import pubsub_v1
 
-    subscriber = pubsub_v1.SubscriberClient()
     topic_name = 'projects/{project_id}/topics/{topic}'.format(
         project_id=os.getenv('GOOGLE_CLOUD_PROJECT'),
         topic='MY_TOPIC_NAME',  # Set this to something appropriate.
     )
+
     subscription_name = 'projects/{project_id}/subscriptions/{sub}'.format(
         project_id=os.getenv('GOOGLE_CLOUD_PROJECT'),
         sub='MY_SUBSCRIPTION_NAME',  # Set this to something appropriate.
     )
-    subscriber.create_subscription(
-        name=subscription_name, topic=topic_name)
 
     def callback(message):
         print(message.data)
         message.ack()
 
-    future = subscriber.subscribe(subscription_name, callback)
+    with pubsub_v1.SubscriberClient() as subscriber:
+        subscriber.create_subscription(
+            name=subscription_name, topic=topic_name)  
+        future = subscriber.subscribe(subscription_name, callback)
 
 The future returned by the call to ``subscriber.subscribe`` can be used to
 block the current thread until a given condition obtains:
diff --git a/docs/publisher/index.rst b/docs/publisher/index.rst
index cd2e5cbea..6810f0232 100644
--- a/docs/publisher/index.rst
+++ b/docs/publisher/index.rst
@@ -33,7 +33,7 @@ Therefore, a very basic publishing call looks like:
 .. code-block:: python
 
     topic = 'projects/{project}/topics/{topic}'
-    publish_client.publish(topic, b'This is my message.')
+    future = publish_client.publish(topic, b'This is my message.')
 
 .. note::
 
@@ -52,7 +52,7 @@ If you want to include attributes, simply add keyword arguments:
 .. code-block:: python
 
     topic = 'projects/{project}/topics/{topic}'
-    publish_client.publish(topic, b'This is my message.', foo='bar')
+    future = publish_client.publish(topic, b'This is my message.', foo='bar')
 
 
 Batching
diff --git a/docs/subscriber/index.rst b/docs/subscriber/index.rst
index 2c9fd91ce..06f1658a4 100644
--- a/docs/subscriber/index.rst
+++ b/docs/subscriber/index.rst
@@ -12,8 +12,9 @@ Instantiating a subscriber client is straightforward:
 .. code-block:: python
 
     from google.cloud import pubsub
-    subscriber = pubsub.SubscriberClient()
 
+    with pubsub.SubscriberClient() as subscriber:
+        # ...
 
 Creating a Subscription
 -----------------------
@@ -41,8 +42,10 @@ to subscribe to, and it must already exist. Once you have that, it is easy:
     # publisher = pubsub.PublisherClient()
 
     topic_path = publisher.topic_path(PROJECT, TOPIC)
-    sub_path = subscriber.subscription_path(PROJECT, SUBSCRIPTION)
-    subscriber.create_subscription(request={"name": sub_path, "topic": topic_path})
+
+    with pubsub.SubscriberClient() as subscriber: 
+        sub_path = subscriber.subscription_path(PROJECT, SUBSCRIPTION)
+        subscriber.create_subscription(request={"name": sub_path, "topic": topic_path})
 
 Once you have created a subscription (or if you already had one), the next
 step is to pull data from it.
@@ -56,6 +59,8 @@ To pull the messages synchronously, use the client's
 
 .. code-block:: python
 
+    # Wrap the following code in `with pubsub.SubscriberClient() as subscriber:`
+
     # Substitute PROJECT and SUBSCRIPTION with appropriate values for your
     # application.
     subscription_path = subscriber.subscription_path(PROJECT, SUBSCRIPTION)
@@ -88,6 +93,8 @@ be dropped by this client and the backend will try to re-deliver them.
 
 .. code-block:: python
 
+    # Wrap the following code in `with pubsub.SubscriberClient() as subscriber:`
+
     ack_ids = []  # TODO: populate with `ack_ids` of the messages to NACK
     ack_deadline_seconds = 0
     subscriber.modify_ack_deadline(
@@ -109,6 +116,8 @@ each message received.
 
 .. code-block:: python
 
+    # Wrap the following code in `with pubsub.SubscriberClient() as subscriber:`
+
     # Substitute PROJECT and SUBSCRIPTION with appropriate values for your
     # application.
     subscription_path = subscriber.subscription_path(PROJECT, SUBSCRIPTION)
@@ -147,6 +156,8 @@ Here is an example:
         do_something_with(message)  # Replace this with your actual logic.
         message.ack()  # Asynchronously acknowledge the message.
 
+    # Wrap the following code in `with pubsub.SubscriberClient() as subscriber:`
+    
     # Substitute PROJECT and SUBSCRIPTION with appropriate values for your
     # application.
     subscription_path = subscriber.subscription_path(PROJECT, SUBSCRIPTION)
@@ -177,7 +188,8 @@ thread will be set on the future.
     try:
         future.result()
     except Exception as ex:
-        subscription.close()
+        # Close the subscriber if not using a context manager.
+        subscriber.close()
         raise
 
 Finally, you can use