Snippets for 'Subscription.{pull,acknowledge,modify_ack_deadline}'.

tseaver · tseaver · commit 51bcf910572f · 2016-04-22T16:22:15.000-04:00
diff --git a/docs/pubsub-usage.rst b/docs/pubsub-usage.rst
@@ -170,61 +170,28 @@ Pull messages from a subscription
 
 Fetch pending messages for a pull subscription:
 
-.. doctest::
-
-   >>> from gcloud import pubsub
-   >>> client = pubsub.Client()
-   >>> topic = client.topic('topic_name')
-   >>> subscription = topic.subscription('subscription_name')
-   >>> with topic.batch() as batch:
-   ...     batch.publish('this is the first message_payload')
-   ...     batch.publish('this is the second message_payload',
-   ...                   attr1='value1', attr2='value2')
-   >>> received = subscription.pull()  # API request
-   >>> messages = [recv[1] for recv in received]
-   >>> [message.message_id for message in messages]
-   [<message_id1>, <message_id2>]
-   >>> [message.data for message in messages]
-   ['this is the first message_payload', 'this is the second message_payload']
-   >>> [message.attributes for message in messages]
-   [{}, {'attr1': 'value1', 'attr2': 'value2'}]
+.. literalinclude:: pubsub_snippets.py
+   :start-after: [START subscription_pull]
+   :end-before: [END subscription_pull]
 
 Note that received messages must be acknowledged, or else the back-end
 will re-send them later:
 
-.. doctest::
-
-   >>> ack_ids = [recv[0] for recv in received]
-   >>> subscription.acknowledge(ack_ids)
-
-Fetch a limited number of pending messages for a pull subscription:
-
-.. doctest::
-
-   >>> from gcloud import pubsub
-   >>> client = pubsub.Client()
-   >>> topic = client.topic('topic_name')
-   >>> subscription = topic.subscription('subscription_name')
-   >>> with topic.batch() as batch:
-   ...     batch.publish('this is the first message_payload')
-   ...     batch.publish('this is the second message_payload',
-   ...                   attr1='value1', attr2='value2')
-   >>> received = subscription.pull(max_messages=1)  # API request
-   >>> messages = [recv[1] for recv in received]
-   >>> [message.message_id for message in messages]
+.. literalinclude:: pubsub_snippets.py
+   :start-after: [START subscription_acknowledge]
+   :end-before: [END subscription_acknowledge]
 
 Fetch messages for a pull subscription without blocking (none pending):
 
-.. doctest::
+.. literalinclude:: pubsub_snippets.py
+   :start-after: [START subscription_pull_return_immediately]
+   :end-before: [END subscription_pull_return_immediately]
 
-   >>> from gcloud import pubsub
-   >>> client = pubsub.Client()
-   >>> topic = client.topic('topic_name')
-   >>> subscription = topic.subscription('subscription_name')
-   >>> received = subscription.pull(return_immediately=True)  # API request
-   >>> messages = [recv[1] for recv in received]
-   >>> [message.message_id for message in messages]
-   []
+Update the acknowlegement deadline for pulled messages:
+
+.. literalinclude:: pubsub_snippets.py
+   :start-after: [START subscription_modify_ack_deadline]
+   :end-before: [END subscription_modify_ack_deadline]
 
 Fetch the IAM policy for a subscription
 
diff --git a/docs/pubsub_snippets.py b/docs/pubsub_snippets.py
@@ -293,6 +293,76 @@ def subscription_lifecycle(client, to_delete):
     # [END subscription_delete]
 
 
+@snippet
+def subscription_pull(client, to_delete):
+    """Pull messges from a subscribed topic."""
+    TOPIC_NAME = 'subscription_pull-%d' % (_millis(),)
+    SUB_NAME = 'subscription_pull-defaults-%d' % (_millis(),)
+    PAYLOAD1 = b'PAYLOAD1'
+    PAYLOAD2 = b'PAYLOAD2'
+    EXTRA = 'EXTRA'
+    topic = client.topic(TOPIC_NAME)
+    topic.create()
+    to_delete.append(topic)
+
+    subscription = topic.subscription(SUB_NAME)
+    subscription.create()
+    to_delete.append(subscription)
+
+    # [START subscription_pull_none_pending]
+    pulled = subscription.pull(max_messages=1)
+    # [END subscription_pull_none_pending]
+    assert len(pulled) == 0
+
+    # [START subscription_pull_return_immediately]
+    pulled = subscription.pull(return_immediately=True)
+    # [END subscription_pull_return_immediately]
+    assert len(pulled) == 0
+
+    topic.publish(PAYLOAD1)
+    topic.publish(PAYLOAD2, extra=EXTRA)
+
+    # [START subscription_pull]
+    pulled = subscription.pull(max_messages=2)
+    # [END subscription_pull]
+
+    assert len(pulled) == 2
+
+    # [START subscription_modify_ack_deadline]
+    for ack_id, _ in pulled:
+        subscription.modify_ack_deadline(ack_id, 90)    # API request
+    # [END subscription_modify_ack_deadline]
+
+    payloads = []
+    extras = []
+
+    def do_something_with(message):  # pylint: disable=unused-argument
+        payloads.append(message.data)
+        if message.attributes:
+            extras.append(message.attributes)
+
+    class ApplicationException(Exception):
+        pass
+
+    def log_exception(_):
+        pass
+
+    # [START subscription_acknowledge]
+    for ack_id, message in pulled:
+        try:
+            do_something_with(message)
+        except ApplicationException as e:
+            log_exception(e)
+        else:
+            subscription.acknowledge([ack_id])
+    # [END subscription_acknowledge]
+
+    assert set(payloads) == set([PAYLOAD1, PAYLOAD2]), 'payloads: %s' % (
+        (payloads,))
+    assert extras == [{'extra': EXTRA}], 'extras: %s' % (
+        (extras,))
+
+
 def _find_examples():
     funcs = [obj for obj in globals().values()
              if getattr(obj, '_snippet', False)]
diff --git a/gcloud/pubsub/subscription.py b/gcloud/pubsub/subscription.py
@@ -267,8 +267,8 @@ def pull(self, return_immediately=False, max_messages=1, client=None):
         Example:
 
         .. literalinclude:: pubsub_snippets.py
-           :start-after: [START subscription_push_pull]
-           :end-before: [END subscription_push_pull]
+           :start-after: [START subscription_pull]
+           :end-before: [END subscription_pull]
 
         :type return_immediately: boolean
         :param return_immediately: if True, the back-end returns even if no
@@ -301,6 +301,12 @@ def acknowledge(self, ack_ids, client=None):
         See:
         https://cloud.google.com/pubsub/reference/rest/v1/projects.subscriptions/acknowledge
 
+        Example:
+
+        .. literalinclude:: pubsub_snippets.py
+           :start-after: [START subscription_acknowledge]
+           :end-before: [END subscription_acknowledge]
+
         :type ack_ids: list of string
         :param ack_ids: ack IDs of messages being acknowledged
 
