From bea4a7b1deec63db1f0d13ad1f09bce524146d06 Mon Sep 17 00:00:00 2001 From: Tres Seaver Date: Mon, 9 Mar 2015 16:30:48 -0400 Subject: [PATCH 1/7] Sketch 'gcloud.pubsub' API. --- docs/conf.py | 1 + docs/index.rst | 1 + docs/pubsub-api.rst | 255 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 257 insertions(+) create mode 100644 docs/pubsub-api.rst diff --git a/docs/conf.py b/docs/conf.py index 3e007d256e20..e1678645944a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -30,6 +30,7 @@ extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', + 'sphinx.ext.doctest', 'sphinx.ext.todo', 'sphinx.ext.viewcode', ] diff --git a/docs/index.rst b/docs/index.rst index 7a8c3f8037cb..56a85a125217 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,6 +13,7 @@ storage-blobs storage-buckets storage-acl + pubsub-api Getting started diff --git a/docs/pubsub-api.rst b/docs/pubsub-api.rst new file mode 100644 index 000000000000..f50fdfd03057 --- /dev/null +++ b/docs/pubsub-api.rst @@ -0,0 +1,255 @@ +``gcloud.pubsub`` API +===================== + +Connection / Authorization +-------------------------- + +- Inferred defaults used to create connection if none configured explicitly: + + - credentials (derived from GAE / GCE environ if present). + + - ``project_id`` (derived from GAE / GCE environ if present). + + - ``scopes`` + + +Manage topics for a project +--------------------------- + +Create a new topic for the default project: + +.. doctest:: + + >>> from gcloud import pubsub + >>> topic = pubsub.create_topic("topic_name") + >>> topic.name + 'topic_name' + +Create a new topic for an explicit project: + +.. doctest:: + + >>> from gcloud import pubsub + >>> topic = pubsub.create_topic("topic_name", project_id='my.project') + >>> topic.name + 'topic_name' + +Fetch an extant topic for the default project: + +.. doctest:: + + >>> from gcloud import pubsub + >>> topic = pubsub.get_topic('topic_name') + >>> topic.name + 'topic_name' + +Fetch an extant topic for the default project: + +.. doctest:: + + >>> from gcloud import pubsub + >>> topic = pubsub.get_topic('topic_name', project_id='my.project') + >>> topic.name + 'topic_name' + +Attempt to fetch a non-extant topic: + +.. doctest:: + + >>> from gcloud import pubsub + >>> pubsub.get_topic('nonesuch') + Traceback (most recent call last): + File "", line 1, in ? + NotFound: ... + +List extant topics for the default project: + +.. doctest:: + + >>> from gcloud import pubsub + >>> [topic.name for topic in pubsub.list_topics()] + ['topic_name'] + +List extant topics for an explicit project: + +.. doctest:: + + >>> from gcloud import pubsub + >>> [topic.name for topic in pubsub.list_topics(project_id='my.project')] + ['topic_name'] + +Delete a topic: + +.. doctest:: + + >>> from gcloud import pubsub + >>> topic = pubsub.get_topic('topic_name') + >>> topic.delete() + + +Publish messages to a topic +--------------------------- + +Publish a single message to a topic, without attributes: + +.. doctest:: + + >>> from gcloud import pubsub + >>> topic = pubsub.get_topic('topic_name') + >>> topic.publish('this is the message_payload') + + +Publish a single message to a topic, with attributes: + +.. doctest:: + + >>> from gcloud import pubsub + >>> topic = pubsub.get_topic('topic_name') + >>> topic.publish('this is another message_payload', + ... attr1='value1', attr2='value2') + + +Publish a set of messages to a topic (as a single request): + +.. doctest:: + + >>> from gcloud import pubsub + >>> topic = pubsub.get_topic('topic_name') + >>> with topic: + ... topic.publish('this is the first message_payload') + ... topic.publish('this is the second message_payload', + ... attr1='value1', attr2='value2') + [, ] + + +Manage subscriptions to topics +------------------------------ + +Create a new "pull" subscription for a topic: + +.. doctest:: + + >>> from gcloud import pubsub + >>> topic = pubsub.get_topic('topic_name') + >>> subscription = topic.create_subscription('subscription_name') + +Create a new "pull" subscription for a topic with a non-default ACK deadline: + +.. doctest:: + + >>> from gcloud import pubsub + >>> topic = pubsub.get_topic('topic_name') + >>> subscription = topic.create_subscription('subscription_name', + ... ack_deadline=90) + +Create a new "push" subscription for a topic: + +.. doctest:: + + >>> ENDPOINT = 'https://example.com/hook' + >>> from gcloud import pubsub + >>> topic = pubsub.get_topic('topic_name') + >>> subscription = topic.create_subscription('subscription_name', + ... push_endpoint=ENDPOINT) + +Get an extant subscription for a topic: + +.. doctest:: + + >>> from gcloud import pubsub + >>> topic = pubsub.get_topic('topic_name') + >>> subscription = topic.get_subscription('subscription_name') + +Attempt to get a non-extant subscription for a topic: + +.. doctest:: + + >>> from gcloud import pubsub + >>> topic = pubsub.get_topic('topic_name') + >>> subscription = topic.get_subscription('nonesuch') + Traceback (most recent call last): + File "", line 1, in ? + NotFound: ... + +Update the ACK deadline for a subscription: + +.. doctest:: + + >>> from gcloud import pubsub + >>> topic = pubsub.get_topic('topic_name') + >>> subscription = topic.get_subscription('subscription_name') + >>> subscription.modify_ack_deadline(90) + +Convert a "pull" subscription to "push": + +.. doctest:: + + >>> ENDPOINT = 'https://example.com/hook' + >>> from gcloud import pubsub + >>> topic = pubsub.get_topic('topic_name') + >>> subscription = topic.get_subscription('subscription_name') + >>> subscription.modify_push_configuration(push_endpoint=ENDPOINT) + +Convert a "push" subscription to "pull": + +.. doctest:: + + >>> ENDPOINT = 'https://example.com/hook' + >>> from gcloud import pubsub + >>> topic = pubsub.get_topic('topic_name') + >>> subscription = topic.create_subscription('subscription_name', + ... push_endpoint=ENDPOINT) + >>> subscription.modify_push_configuration(push_endpoint=None) + +List extant subscriptions for a topic: + +.. doctest:: + + >>> from gcloud import pubsub + >>> topic = pubsub.get_topic('topic_name') + >>> [subscription.name for subscription in topic.list_subscriptions()] + ['subscription_name'] + +Delete a subscription: + +.. doctest:: + + >>> from gcloud import pubsub + >>> topic = pubsub.get_topic('topic_name') + >>> subscription = topic.get_subscription('subscription_name') + >>> subscription.delete() + + +Pull messages from a subscription +--------------------------------- + +Fetch pending messages for a "pull" subscription (the messages will have +been ACKed already): + +.. doctest:: + + >>> from gcloud import pubsub + >>> topic = pubsub.get_topic('topic_name') + >>> subscription = topic.get_subscription('subscription_name') + >>> [message.id for message in subscription.pull()] + [, , ...] + +Fetch a limited number of pending messages for a "pull" subscription: + +.. doctest:: + + >>> from gcloud import pubsub + >>> topic = pubsub.get_topic('topic_name') + >>> subscription = topic.get_subscription('subscription_name') + >>> [message.id for message in subscription.pull(max_messages=2)] + [, ] + +Fetch messages for a "pull" subscription without blocking (none pending): + +.. doctest:: + + >>> from gcloud import pubsub + >>> topic = pubsub.get_topic('topic_name') + >>> subscription = topic.get_subscription('subscription_name') + >>> [message.id for message in subscription.pull(return_immediately=True)] + [] From 883574edb2dbbf5af0be381557f47a2afa8a470d Mon Sep 17 00:00:00 2001 From: Tres Seaver Date: Thu, 12 Mar 2015 13:24:41 -0400 Subject: [PATCH 2/7] Use consistent double quotes. Addresses: https://github.com/GoogleCloudPlatform/gcloud-python/pull/691#discussion_r26077058 --- docs/pubsub-api.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/pubsub-api.rst b/docs/pubsub-api.rst index f50fdfd03057..8d2d229f2f5b 100644 --- a/docs/pubsub-api.rst +++ b/docs/pubsub-api.rst @@ -30,7 +30,7 @@ Create a new topic for an explicit project: .. doctest:: >>> from gcloud import pubsub - >>> topic = pubsub.create_topic("topic_name", project_id='my.project') + >>> topic = pubsub.create_topic("topic_name", project_id="my.project") >>> topic.name 'topic_name' @@ -48,7 +48,7 @@ Fetch an extant topic for the default project: .. doctest:: >>> from gcloud import pubsub - >>> topic = pubsub.get_topic('topic_name', project_id='my.project') + >>> topic = pubsub.get_topic('topic_name', project_id="my.project") >>> topic.name 'topic_name' @@ -75,7 +75,7 @@ List extant topics for an explicit project: .. doctest:: >>> from gcloud import pubsub - >>> [topic.name for topic in pubsub.list_topics(project_id='my.project')] + >>> [topic.name for topic in pubsub.list_topics(project_id="my.project")] ['topic_name'] Delete a topic: From 9d82cf5243e595620c7a7aae5b7d504081216403 Mon Sep 17 00:00:00 2001 From: Tres Seaver Date: Thu, 12 Mar 2015 13:26:16 -0400 Subject: [PATCH 3/7] Don't wrap pull / push in quotes. Addresses: https://github.com/GoogleCloudPlatform/gcloud-python/pull/691#discussion_r26077195 --- docs/pubsub-api.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/pubsub-api.rst b/docs/pubsub-api.rst index 8d2d229f2f5b..dc69dd50c3b0 100644 --- a/docs/pubsub-api.rst +++ b/docs/pubsub-api.rst @@ -125,7 +125,7 @@ Publish a set of messages to a topic (as a single request): Manage subscriptions to topics ------------------------------ -Create a new "pull" subscription for a topic: +Create a new pull subscription for a topic: .. doctest:: @@ -133,7 +133,7 @@ Create a new "pull" subscription for a topic: >>> topic = pubsub.get_topic('topic_name') >>> subscription = topic.create_subscription('subscription_name') -Create a new "pull" subscription for a topic with a non-default ACK deadline: +Create a new pull subscription for a topic with a non-default ACK deadline: .. doctest:: @@ -142,7 +142,7 @@ Create a new "pull" subscription for a topic with a non-default ACK deadline: >>> subscription = topic.create_subscription('subscription_name', ... ack_deadline=90) -Create a new "push" subscription for a topic: +Create a new push subscription for a topic: .. doctest:: @@ -180,7 +180,7 @@ Update the ACK deadline for a subscription: >>> subscription = topic.get_subscription('subscription_name') >>> subscription.modify_ack_deadline(90) -Convert a "pull" subscription to "push": +Convert a pull subscription to push: .. doctest:: @@ -190,7 +190,7 @@ Convert a "pull" subscription to "push": >>> subscription = topic.get_subscription('subscription_name') >>> subscription.modify_push_configuration(push_endpoint=ENDPOINT) -Convert a "push" subscription to "pull": +Convert a push subscription to pull: .. doctest:: @@ -223,7 +223,7 @@ Delete a subscription: Pull messages from a subscription --------------------------------- -Fetch pending messages for a "pull" subscription (the messages will have +Fetch pending messages for a pull subscription (the messages will have been ACKed already): .. doctest:: @@ -234,7 +234,7 @@ been ACKed already): >>> [message.id for message in subscription.pull()] [, , ...] -Fetch a limited number of pending messages for a "pull" subscription: +Fetch a limited number of pending messages for a pull subscription: .. doctest:: @@ -244,7 +244,7 @@ Fetch a limited number of pending messages for a "pull" subscription: >>> [message.id for message in subscription.pull(max_messages=2)] [, ] -Fetch messages for a "pull" subscription without blocking (none pending): +Fetch messages for a pull subscription without blocking (none pending): .. doctest:: From 0549543a75f2f951e9fd4e3625a00e4da0914467 Mon Sep 17 00:00:00 2001 From: Tres Seaver Date: Fri, 13 Mar 2015 12:07:02 -0400 Subject: [PATCH 4/7] Avoid API requests when instantiating topics / subscriptions. --- docs/pubsub-api.rst | 202 ++++++++++++++++++++------------------------ 1 file changed, 92 insertions(+), 110 deletions(-) diff --git a/docs/pubsub-api.rst b/docs/pubsub-api.rst index dc69dd50c3b0..1f194a95406f 100644 --- a/docs/pubsub-api.rst +++ b/docs/pubsub-api.rst @@ -20,71 +20,51 @@ Create a new topic for the default project: .. doctest:: - >>> from gcloud import pubsub - >>> topic = pubsub.create_topic("topic_name") - >>> topic.name - 'topic_name' + >>> from gcloud.pubsub.topic import Topic + >>> topic = Topic("topic_name") + >>> topic.create() # API request Create a new topic for an explicit project: .. doctest:: - >>> from gcloud import pubsub - >>> topic = pubsub.create_topic("topic_name", project_id="my.project") - >>> topic.name - 'topic_name' - -Fetch an extant topic for the default project: - -.. doctest:: - - >>> from gcloud import pubsub - >>> topic = pubsub.get_topic('topic_name') - >>> topic.name - 'topic_name' - -Fetch an extant topic for the default project: - -.. doctest:: - - >>> from gcloud import pubsub - >>> topic = pubsub.get_topic('topic_name', project_id="my.project") - >>> topic.name - 'topic_name' + >>> from gcloud.pubsub.topic import Topic + >>> topic = Topic("topic_name", project_id="my.project") + >>> topic.create() # API request -Attempt to fetch a non-extant topic: +Check for the existance of a topic: .. doctest:: - >>> from gcloud import pubsub - >>> pubsub.get_topic('nonesuch') - Traceback (most recent call last): - File "", line 1, in ? - NotFound: ... + >>> from gcloud.pubsub.topic import Topic + >>> topic = Topic("topic_name") + >>> topic.exists() # API request + True -List extant topics for the default project: +List topics for the default project: .. doctest:: >>> from gcloud import pubsub - >>> [topic.name for topic in pubsub.list_topics()] + >>> [topic.name for topic in pubsub.list_topics()] # API request ['topic_name'] -List extant topics for an explicit project: +List topics for an explicit project: .. doctest:: >>> from gcloud import pubsub - >>> [topic.name for topic in pubsub.list_topics(project_id="my.project")] + >>> topics = pubsub.list_topics(project_id="my.project") # API request + >>> [topic.name for topic in topics] ['topic_name'] Delete a topic: .. doctest:: - >>> from gcloud import pubsub - >>> topic = pubsub.get_topic('topic_name') - >>> topic.delete() + >>> from gcloud.pubsub.topic import Topic + >>> topic = Topic("topic_name") + >>> topic.delete() # API request Publish messages to a topic @@ -94,33 +74,38 @@ Publish a single message to a topic, without attributes: .. doctest:: - >>> from gcloud import pubsub - >>> topic = pubsub.get_topic('topic_name') - >>> topic.publish('this is the message_payload') + >>> from gcloud.pubsub.topic import Topic + >>> topic = Topic("topic_name") + >>> topic.publish('this is the message_payload') # API request Publish a single message to a topic, with attributes: .. doctest:: - >>> from gcloud import pubsub - >>> topic = pubsub.get_topic('topic_name') + >>> from gcloud.pubsub.topic import Topic + >>> topic = Topic("topic_name") >>> topic.publish('this is another message_payload', - ... attr1='value1', attr2='value2') + ... attr1='value1', attr2='value2') # API request Publish a set of messages to a topic (as a single request): .. doctest:: - >>> from gcloud import pubsub - >>> topic = pubsub.get_topic('topic_name') + >>> from gcloud.pubsub.topic import Topic + >>> topic = Topic("topic_name") >>> with topic: ... topic.publish('this is the first message_payload') ... topic.publish('this is the second message_payload', ... attr1='value1', attr2='value2') [, ] +.. note:: + + The only API request happens during the ``__exit__()`` of the topic + used as a context manager. + Manage subscriptions to topics ------------------------------ @@ -129,108 +114,102 @@ Create a new pull subscription for a topic: .. doctest:: - >>> from gcloud import pubsub - >>> topic = pubsub.get_topic('topic_name') - >>> subscription = topic.create_subscription('subscription_name') + >>> from gcloud.pubsub.topic import Topic + >>> from gcloud.pubsub.subscription import Subscription + >>> topic = Topic("topic_name") + >>> subscription = Subscription('subscription_name', topic) + >>> subscription.create() # API request Create a new pull subscription for a topic with a non-default ACK deadline: .. doctest:: - >>> from gcloud import pubsub - >>> topic = pubsub.get_topic('topic_name') - >>> subscription = topic.create_subscription('subscription_name', - ... ack_deadline=90) + >>> from gcloud.pubsub.topic import Topic + >>> from gcloud.pubsub.subscription import Subscription + >>> topic = Topic("topic_name") + >>> subscription = Subscription('subscription_name', ack_deadline=90) + >>> subscription.create() # API request Create a new push subscription for a topic: .. doctest:: >>> ENDPOINT = 'https://example.com/hook' - >>> from gcloud import pubsub - >>> topic = pubsub.get_topic('topic_name') - >>> subscription = topic.create_subscription('subscription_name', - ... push_endpoint=ENDPOINT) + >>> from gcloud.pubsub.topic import Topic + >>> from gcloud.pubsub.subscription import Subscription + >>> topic = Topic("topic_name") + >>> subscription = Subscription('subscription_name', push_endpoint=ENDPOINT) + >>> subscription.create() # API request -Get an extant subscription for a topic: +Check for the existence of a subscription: .. doctest:: - >>> from gcloud import pubsub - >>> topic = pubsub.get_topic('topic_name') - >>> subscription = topic.get_subscription('subscription_name') - -Attempt to get a non-extant subscription for a topic: - -.. doctest:: - - >>> from gcloud import pubsub - >>> topic = pubsub.get_topic('topic_name') - >>> subscription = topic.get_subscription('nonesuch') - Traceback (most recent call last): - File "", line 1, in ? - NotFound: ... - -Update the ACK deadline for a subscription: - -.. doctest:: - - >>> from gcloud import pubsub - >>> topic = pubsub.get_topic('topic_name') - >>> subscription = topic.get_subscription('subscription_name') - >>> subscription.modify_ack_deadline(90) + >>> from gcloud.pubsub.topic import Topic + >>> from gcloud.pubsub.subscription import Subscription + >>> topic = Topic("topic_name") + >>> subscription = Subscription('subscription_name', topic) + >>> subscription.exists() # API request + True Convert a pull subscription to push: .. doctest:: >>> ENDPOINT = 'https://example.com/hook' - >>> from gcloud import pubsub - >>> topic = pubsub.get_topic('topic_name') - >>> subscription = topic.get_subscription('subscription_name') - >>> subscription.modify_push_configuration(push_endpoint=ENDPOINT) + >>> from gcloud.pubsub.topic import Topic + >>> from gcloud.pubsub.subscription import Subscription + >>> topic = Topic("topic_name") + >>> subscription = Subscription('subscription_name', topic) + >>> subscription.modify_push_configuration(push_endpoint=ENDPOINT) # API request Convert a push subscription to pull: .. doctest:: >>> ENDPOINT = 'https://example.com/hook' - >>> from gcloud import pubsub - >>> topic = pubsub.get_topic('topic_name') - >>> subscription = topic.create_subscription('subscription_name', - ... push_endpoint=ENDPOINT) - >>> subscription.modify_push_configuration(push_endpoint=None) + >>> from gcloud.pubsub.topic import Topic + >>> topic = Topic("topic_name") + >>> subscription = Subscription('subscription_name', topic, + ... push_endpoint=ENDPOINT) + >>> subscription.modify_push_configuration(push_endpoint=None) # API request -List extant subscriptions for a topic: +List subscriptions for a topic: .. doctest:: - >>> from gcloud import pubsub - >>> topic = pubsub.get_topic('topic_name') - >>> [subscription.name for subscription in topic.list_subscriptions()] + >>> from gcloud.pubsub.topic import Topic + >>> topic = Topic("topic_name") + >>> subscriptions = topic.list_subscriptions() # API request + >>> [subscription.name for subscription in subscriptions] ['subscription_name'] Delete a subscription: .. doctest:: - >>> from gcloud import pubsub - >>> topic = pubsub.get_topic('topic_name') - >>> subscription = topic.get_subscription('subscription_name') - >>> subscription.delete() + >>> from gcloud.pubsub.topic import Topic + >>> from gcloud.pubsub.subscription import Subscription + >>> topic = Topic("topic_name") + >>> subscription = Subscription('subscription_name', topic) + >>> subscription.delete() # API request Pull messages from a subscription --------------------------------- -Fetch pending messages for a pull subscription (the messages will have -been ACKed already): +Fetch pending messages for a pull subscription + +.. note:: + + The messages will have been ACKed already. .. doctest:: - >>> from gcloud import pubsub - >>> topic = pubsub.get_topic('topic_name') - >>> subscription = topic.get_subscription('subscription_name') + >>> from gcloud.pubsub.topic import Topic + >>> from gcloud.pubsub.subscription import Subscription + >>> topic = Topic("topic_name") + >>> subscription = Subscription('subscription_name', topic) >>> [message.id for message in subscription.pull()] [, , ...] @@ -238,9 +217,10 @@ Fetch a limited number of pending messages for a pull subscription: .. doctest:: - >>> from gcloud import pubsub - >>> topic = pubsub.get_topic('topic_name') - >>> subscription = topic.get_subscription('subscription_name') + >>> from gcloud.pubsub.topic import Topic + >>> from gcloud.pubsub.subscription import Subscription + >>> topic = Topic("topic_name") + >>> subscription = Subscription('subscription_name', topic) >>> [message.id for message in subscription.pull(max_messages=2)] [, ] @@ -248,8 +228,10 @@ Fetch messages for a pull subscription without blocking (none pending): .. doctest:: - >>> from gcloud import pubsub - >>> topic = pubsub.get_topic('topic_name') - >>> subscription = topic.get_subscription('subscription_name') + >>> from gcloud.pubsub.topic import Topic + >>> from gcloud.pubsub.subscription import Subscription + >>> topic = Topic("topic_name") + >>> subscription = Subscription('subscription_name', topic) >>> [message.id for message in subscription.pull(return_immediately=True)] [] + From 1ade18f0d81cd796bb833d50c3e936284eb684f2 Mon Sep 17 00:00:00 2001 From: Tres Seaver Date: Fri, 13 Mar 2015 12:13:57 -0400 Subject: [PATCH 5/7] Consistent quotes. --- docs/pubsub-api.rst | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/pubsub-api.rst b/docs/pubsub-api.rst index 1f194a95406f..7206028fae30 100644 --- a/docs/pubsub-api.rst +++ b/docs/pubsub-api.rst @@ -21,7 +21,7 @@ Create a new topic for the default project: .. doctest:: >>> from gcloud.pubsub.topic import Topic - >>> topic = Topic("topic_name") + >>> topic = Topic('topic_name') >>> topic.create() # API request Create a new topic for an explicit project: @@ -29,7 +29,7 @@ Create a new topic for an explicit project: .. doctest:: >>> from gcloud.pubsub.topic import Topic - >>> topic = Topic("topic_name", project_id="my.project") + >>> topic = Topic('topic_name', project_id='my.project') >>> topic.create() # API request Check for the existance of a topic: @@ -37,7 +37,7 @@ Check for the existance of a topic: .. doctest:: >>> from gcloud.pubsub.topic import Topic - >>> topic = Topic("topic_name") + >>> topic = Topic('topic_name') >>> topic.exists() # API request True @@ -54,7 +54,7 @@ List topics for an explicit project: .. doctest:: >>> from gcloud import pubsub - >>> topics = pubsub.list_topics(project_id="my.project") # API request + >>> topics = pubsub.list_topics(project_id='my.project') # API request >>> [topic.name for topic in topics] ['topic_name'] @@ -63,7 +63,7 @@ Delete a topic: .. doctest:: >>> from gcloud.pubsub.topic import Topic - >>> topic = Topic("topic_name") + >>> topic = Topic('topic_name') >>> topic.delete() # API request @@ -75,7 +75,7 @@ Publish a single message to a topic, without attributes: .. doctest:: >>> from gcloud.pubsub.topic import Topic - >>> topic = Topic("topic_name") + >>> topic = Topic('topic_name') >>> topic.publish('this is the message_payload') # API request @@ -84,7 +84,7 @@ Publish a single message to a topic, with attributes: .. doctest:: >>> from gcloud.pubsub.topic import Topic - >>> topic = Topic("topic_name") + >>> topic = Topic('topic_name') >>> topic.publish('this is another message_payload', ... attr1='value1', attr2='value2') # API request @@ -94,7 +94,7 @@ Publish a set of messages to a topic (as a single request): .. doctest:: >>> from gcloud.pubsub.topic import Topic - >>> topic = Topic("topic_name") + >>> topic = Topic('topic_name') >>> with topic: ... topic.publish('this is the first message_payload') ... topic.publish('this is the second message_payload', @@ -116,7 +116,7 @@ Create a new pull subscription for a topic: >>> from gcloud.pubsub.topic import Topic >>> from gcloud.pubsub.subscription import Subscription - >>> topic = Topic("topic_name") + >>> topic = Topic('topic_name') >>> subscription = Subscription('subscription_name', topic) >>> subscription.create() # API request @@ -126,7 +126,7 @@ Create a new pull subscription for a topic with a non-default ACK deadline: >>> from gcloud.pubsub.topic import Topic >>> from gcloud.pubsub.subscription import Subscription - >>> topic = Topic("topic_name") + >>> topic = Topic('topic_name') >>> subscription = Subscription('subscription_name', ack_deadline=90) >>> subscription.create() # API request @@ -137,7 +137,7 @@ Create a new push subscription for a topic: >>> ENDPOINT = 'https://example.com/hook' >>> from gcloud.pubsub.topic import Topic >>> from gcloud.pubsub.subscription import Subscription - >>> topic = Topic("topic_name") + >>> topic = Topic('topic_name') >>> subscription = Subscription('subscription_name', push_endpoint=ENDPOINT) >>> subscription.create() # API request @@ -147,7 +147,7 @@ Check for the existence of a subscription: >>> from gcloud.pubsub.topic import Topic >>> from gcloud.pubsub.subscription import Subscription - >>> topic = Topic("topic_name") + >>> topic = Topic('topic_name') >>> subscription = Subscription('subscription_name', topic) >>> subscription.exists() # API request True @@ -159,7 +159,7 @@ Convert a pull subscription to push: >>> ENDPOINT = 'https://example.com/hook' >>> from gcloud.pubsub.topic import Topic >>> from gcloud.pubsub.subscription import Subscription - >>> topic = Topic("topic_name") + >>> topic = Topic('topic_name') >>> subscription = Subscription('subscription_name', topic) >>> subscription.modify_push_configuration(push_endpoint=ENDPOINT) # API request @@ -169,7 +169,7 @@ Convert a push subscription to pull: >>> ENDPOINT = 'https://example.com/hook' >>> from gcloud.pubsub.topic import Topic - >>> topic = Topic("topic_name") + >>> topic = Topic('topic_name') >>> subscription = Subscription('subscription_name', topic, ... push_endpoint=ENDPOINT) >>> subscription.modify_push_configuration(push_endpoint=None) # API request @@ -179,7 +179,7 @@ List subscriptions for a topic: .. doctest:: >>> from gcloud.pubsub.topic import Topic - >>> topic = Topic("topic_name") + >>> topic = Topic('topic_name') >>> subscriptions = topic.list_subscriptions() # API request >>> [subscription.name for subscription in subscriptions] ['subscription_name'] @@ -190,7 +190,7 @@ Delete a subscription: >>> from gcloud.pubsub.topic import Topic >>> from gcloud.pubsub.subscription import Subscription - >>> topic = Topic("topic_name") + >>> topic = Topic('topic_name') >>> subscription = Subscription('subscription_name', topic) >>> subscription.delete() # API request @@ -208,7 +208,7 @@ Fetch pending messages for a pull subscription >>> from gcloud.pubsub.topic import Topic >>> from gcloud.pubsub.subscription import Subscription - >>> topic = Topic("topic_name") + >>> topic = Topic('topic_name') >>> subscription = Subscription('subscription_name', topic) >>> [message.id for message in subscription.pull()] [, , ...] @@ -219,7 +219,7 @@ Fetch a limited number of pending messages for a pull subscription: >>> from gcloud.pubsub.topic import Topic >>> from gcloud.pubsub.subscription import Subscription - >>> topic = Topic("topic_name") + >>> topic = Topic('topic_name') >>> subscription = Subscription('subscription_name', topic) >>> [message.id for message in subscription.pull(max_messages=2)] [, ] @@ -230,7 +230,7 @@ Fetch messages for a pull subscription without blocking (none pending): >>> from gcloud.pubsub.topic import Topic >>> from gcloud.pubsub.subscription import Subscription - >>> topic = Topic("topic_name") + >>> topic = Topic('topic_name') >>> subscription = Subscription('subscription_name', topic) >>> [message.id for message in subscription.pull(return_immediately=True)] [] From ed47ae0f14c90b2fdf21ca9658c3d83d19b68d94 Mon Sep 17 00:00:00 2001 From: Tres Seaver Date: Fri, 13 Mar 2015 12:15:51 -0400 Subject: [PATCH 6/7] Clarify: using topic as context mgr returns a list aggregating message IDs. --- docs/pubsub-api.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/pubsub-api.rst b/docs/pubsub-api.rst index 7206028fae30..0782789a0574 100644 --- a/docs/pubsub-api.rst +++ b/docs/pubsub-api.rst @@ -95,10 +95,11 @@ Publish a set of messages to a topic (as a single request): >>> from gcloud.pubsub.topic import Topic >>> topic = Topic('topic_name') - >>> with topic: + >>> with topic as batch: ... topic.publish('this is the first message_payload') ... topic.publish('this is the second message_payload', ... attr1='value1', attr2='value2') + >>> batch [, ] .. note:: From ba5c5d3854e8273db8b850dda1ff600f361772b0 Mon Sep 17 00:00:00 2001 From: Tres Seaver Date: Fri, 13 Mar 2015 12:16:32 -0400 Subject: [PATCH 7/7] Make 'pull' examples more explicit by publising to the topic. --- docs/pubsub-api.rst | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/docs/pubsub-api.rst b/docs/pubsub-api.rst index 0782789a0574..2893879ad6ea 100644 --- a/docs/pubsub-api.rst +++ b/docs/pubsub-api.rst @@ -211,8 +211,17 @@ Fetch pending messages for a pull subscription >>> from gcloud.pubsub.subscription import Subscription >>> topic = Topic('topic_name') >>> subscription = Subscription('subscription_name', topic) - >>> [message.id for message in subscription.pull()] - [, , ...] + >>> with topic: + ... topic.publish('this is the first message_payload') + ... topic.publish('this is the second message_payload', + ... attr1='value1', attr2='value2') + >>> messages = subscription.pull() # API request + >>> [message.id for message in messages] + [, ] + >>> [message.data for message in messages] + ['this is the first message_payload', 'this is the second message_payload'] + >>> [message.attrs for message in messages] + [{}, {'attr1': 'value1', 'attr2': 'value2'}] Fetch a limited number of pending messages for a pull subscription: @@ -222,8 +231,12 @@ Fetch a limited number of pending messages for a pull subscription: >>> from gcloud.pubsub.subscription import Subscription >>> topic = Topic('topic_name') >>> subscription = Subscription('subscription_name', topic) - >>> [message.id for message in subscription.pull(max_messages=2)] - [, ] + >>> with topic: + ... topic.publish('this is the first message_payload') + ... topic.publish('this is the second message_payload', + ... attr1='value1', attr2='value2') + >>> [message.id for message in subscription.pull(max_messages=1)] + [] Fetch messages for a pull subscription without blocking (none pending):