-
Notifications
You must be signed in to change notification settings - Fork 1.5k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Sketch 'gcloud.pubsub' API. #691
Changes from 3 commits
bea4a7b
883574e
9d82cf5
0549543
1ade18f
ed47ae0
ba5c5d3
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -13,6 +13,7 @@ | |
storage-blobs | ||
storage-buckets | ||
storage-acl | ||
pubsub-api | ||
|
||
|
||
Getting started | ||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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") | ||
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong. |
||
>>> 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: | ||
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong. |
||
|
||
.. 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') | ||
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong. |
||
Traceback (most recent call last): | ||
File "<stdin>", line 1, in ? | ||
NotFound: ... | ||
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong. |
||
|
||
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() | ||
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong. |
||
|
||
|
||
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') | ||
<message_id> | ||
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong. |
||
|
||
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') | ||
<message_id> | ||
|
||
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: | ||
This comment was marked as spam.
Sorry, something went wrong. |
||
... topic.publish('this is the first message_payload') | ||
... topic.publish('this is the second message_payload', | ||
... attr1='value1', attr2='value2') | ||
[<message_id1>, <message_id2>] | ||
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong. |
||
|
||
|
||
Manage subscriptions to topics | ||
------------------------------ | ||
|
||
Create a new pull subscription for a topic: | ||
|
||
.. doctest:: | ||
|
||
>>> from gcloud import pubsub | ||
>>> topic = pubsub.get_topic('topic_name') | ||
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong. |
||
>>> subscription = topic.create_subscription('subscription_name') | ||
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong. |
||
|
||
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', | ||
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong. |
||
... 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 "<stdin>", line 1, in ? | ||
NotFound: ... | ||
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong. |
||
|
||
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) | ||
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong. |
||
|
||
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()] | ||
[<message_id1>, <message_id2>, ...] | ||
|
||
Fetch a limited number of pending messages for a pull subscription: | ||
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong. |
||
|
||
.. 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)] | ||
[<message_id1>, <message_id2>] | ||
|
||
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)] | ||
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong. |
||
[] |
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong.