Attempt at implementing clients for Pub/Sub

docs/pubsub-api.rst

@@ -5,25 +5,18 @@
 Pub/Sub
 -------
 
-:mod:`gcloud.pubsub`
-~~~~~~~~~~~~~~~~~~~~~~~
-
-.. automodule:: gcloud.pubsub
- :members: get_connection, get_default_connection,
- set_default_connection, set_defaults
-
-Connections
+Client
 ~~~~~~~~~~~
 
-.. automodule:: gcloud.pubsub.connection
+.. automodule:: gcloud.pubsub.client
  :members:
  :undoc-members:
  :show-inheritance:
 
-Interacting with the API
-~~~~~~~~~~~~~~~~~~~~~~~~
+Connections
+~~~~~~~~~~~
 
-.. automodule:: gcloud.pubsub.api
+.. automodule:: gcloud.pubsub.connection
  :members:
  :undoc-members:
  :show-inheritance:

docs/pubsub-usage.rst

@@ -1,16 +1,28 @@
 Using the API
 =============
 
-Connection / Authorization
---------------------------
+Authorization / Configuration
+-----------------------------
 
-- Inferred defaults used to create connection if none configured explicitly:
+- Use :class:`Client <gcloud.pubsub.client.Client>` objects to configure
+ your applications.
 
- - credentials (derived from GAE / GCE environ if present).
+- :class:`Client <gcloud.pubsub.client.Client>` objects hold both a ``project``
+ and an authenticated connection to the PubSub service.
 
- - ``project`` (derived from GAE / GCE environ if present).
+- The authentication credentials can be implicitly determined from the
+ environment or directly via
+ :meth:`from_service_account_json <gcloud.pubsub.client.Client.from_service_account_json>`
+ and
+ :meth:`from_service_account_p12 <gcloud.pubsub.client.Client.from_service_account_p12>`.
 
- - ``scopes``
+- After setting ``GOOGLE_APPLICATION_CREDENTIALS`` and ``GCLOUD_PROJECT``
+ environment variables, create a :class:`Client <gcloud.pubsub.client.Client>`
+
+ .. doctest::
+
+ >>> from gcloud import pubsub
+ >>> client = pubsub.Client()
 
 
 Manage topics for a project
@@ -20,51 +32,38 @@ Create a new topic for the default project:
 
 .. doctest::
 
- >>> from gcloud.pubsub import Topic
- >>> topic = Topic('topic_name')
- >>> topic.create() # API request
-
-Create a new topic for an explicit project:
-
-.. doctest::
-
- >>> from gcloud.pubsub import Topic
- >>> topic = Topic('topic_name', project='my.project')
+ >>> from gcloud import pubsub
+ >>> client = pubsub.Client()
+ >>> topic = client.topic('topic_name')
  >>> topic.create() # API request
 
-Check for the existance of a topic:
+Check for the existence of a topic:
 
 .. doctest::
 
- >>> from gcloud.pubsub import Topic
- >>> topic = Topic('topic_name')
+ >>> from gcloud import pubsub
+ >>> client = pubsub.Client()
+ >>> topic = client.topic('topic_name')
  >>> topic.exists() # API request
  True
 
 List topics for the default project:
 
 .. doctest::
 
- >>> from gcloud.pubsub import list_topics
- >>> topics, next_page_token = list_topics() # API request
- >>> [topic.name for topic in topics]
- ['topic_name']
-
-List topics for an explicit project:
-
-.. doctest::
-
- >>> from gcloud.pubsub import list_topics
- >>> topics, next_page_token = list_topics(project='my.project') # API request
+ >>> from gcloud import pubsub
+ >>> client = pubsub.Client()
+ >>> topics, next_page_token = client.list_topics() # API request
  >>> [topic.name for topic in topics]
  ['topic_name']
 
 Delete a topic:
 
 .. doctest::
 
- >>> from gcloud.pubsub import Topic
- >>> topic = Topic('topic_name')
+ >>> from gcloud import pubsub
+ >>> client = pubsub.Client()
+ >>> topic = client.topic('topic_name')
  >>> topic.delete() # API request
 
 
@@ -75,17 +74,19 @@ Publish a single message to a topic, without attributes:
 
 .. doctest::
 
- >>> from gcloud.pubsub import Topic
- >>> topic = Topic('topic_name')
+ >>> from gcloud import pubsub
+ >>> client = pubsub.Client()
+ >>> topic = client.topic('topic_name')
  >>> topic.publish('this is the message_payload') # API request
  <message_id>
 
 Publish a single message to a topic, with attributes:
 
 .. doctest::
 
- >>> from gcloud.pubsub import Topic
- >>> topic = Topic('topic_name')
+ >>> from gcloud import pubsub
+ >>> client = pubsub.Client()
+ >>> topic = client.topic('topic_name')
  >>> topic.publish('this is another message_payload',
  ... attr1='value1', attr2='value2') # API request
  <message_id>
@@ -94,8 +95,9 @@ Publish a set of messages to a topic (as a single request):
 
 .. doctest::
 
- >>> from gcloud.pubsub import Topic
- >>> topic = Topic('topic_name')
+ >>> from gcloud import pubsub
+ >>> client = pubsub.Client()
+ >>> topic = client.topic('topic_name')
  >>> with topic.batch() as batch:
  ... batch.publish('this is the first message_payload')
  ... batch.publish('this is the second message_payload',
@@ -116,93 +118,98 @@ Create a new pull subscription for a topic:
 
 .. doctest::
 
- >>> from gcloud.pubsub import Topic
- >>> from gcloud.pubsub import Subscription
- >>> topic = Topic('topic_name')
- >>> subscription = Subscription('subscription_name', topic)
+ >>> from gcloud import pubsub
+ >>> client = pubsub.Client()
+ >>> topic = client.topic('topic_name')
+ >>> subscription = pubsub.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.pubsub import Topic
- >>> from gcloud.pubsub import Subscription
- >>> topic = Topic('topic_name')
- >>> subscription = Subscription('subscription_name', ack_deadline=90)
+ >>> from gcloud import pubsub
+ >>> client = pubsub.Client()
+ >>> topic = client.topic('topic_name')
+ >>> subscription = pubsub.Subscription('subscription_name', topic,
+ ... ack_deadline=90)
  >>> subscription.create() # API request
 
 Create a new push subscription for a topic:
 
 .. doctest::
 
+ >>> from gcloud import pubsub
  >>> ENDPOINT = 'https://example.com/hook'
- >>> from gcloud.pubsub import Topic
- >>> from gcloud.pubsub import Subscription
- >>> topic = Topic('topic_name')
->>> subscription = Subscription('subscription_name', push_endpoint=ENDPOINT)
+ >>> client = pubsub.Client()
+ >>> topic = client.topic('topic_name')
+ >>> subscription = pubsub.Subscription('subscription_name', topic,
+...  push_endpoint=ENDPOINT)
  >>> subscription.create() # API request
 
 Check for the existence of a subscription:
 
 .. doctest::
 
- >>> from gcloud.pubsub import Topic
- >>> from gcloud.pubsub import Subscription
- >>> topic = Topic('topic_name')
- >>> subscription = Subscription('subscription_name', topic)
+ >>> from gcloud import pubsub
+ >>> client = pubsub.Client()
+ >>> topic = client.topic('topic_name')
+ >>> subscription = pubsub.Subscription('subscription_name', topic)
  >>> subscription.exists() # API request
  True
 
 Convert a pull subscription to push:
 
 .. doctest::
 
+ >>> from gcloud import pubsub
  >>> ENDPOINT = 'https://example.com/hook'
- >>> from gcloud.pubsub import Topic
- >>> from gcloud.pubsub import Subscription
- >>> topic = Topic('topic_name')
- >>> subscription = Subscription('subscription_name', topic)
+ >>> client = pubsub.Client()
+ >>> topic = client.topic('topic_name')
+ >>> subscription = pubsub.Subscription('subscription_name', topic)
  >>> subscription.modify_push_configuration(push_endpoint=ENDPOINT) # API request
 
 Convert a push subscription to pull:
 
 .. doctest::
 
+ >>> from gcloud import pubsub
  >>> ENDPOINT = 'https://example.com/hook'
- >>> from gcloud.pubsub import Topic
- >>> topic = Topic('topic_name')
- >>> subscription = Subscription('subscription_name', topic,
- ... push_endpoint=ENDPOINT)
+ >>> client = pubsub.Client()
+ >>> topic = client.topic('topic_name')
+ >>> subscription = pubusb.Subscription('subscription_name', topic,
+ ... push_endpoint=ENDPOINT)
  >>> subscription.modify_push_configuration(push_endpoint=None) # API request
 
 List subscriptions for a topic:
 
 .. doctest::
 
- >>> from gcloud.pubsub import Topic
- >>> topic = Topic('topic_name')
- >>> subscriptions, next_page_token = topic.list_subscriptions() # API request
+ >>> from gcloud import pubsub
+ >>> client = pubsub.Client()
+ >>> subscriptions, next_page_token = client.list_subscriptions(
+ ... topic_name='topic_name') # API request
  >>> [subscription.name for subscription in subscriptions]
  ['subscription_name']
 
 List all subscriptions for the default project:
 
 .. doctest::
 
- >>> from gcloud.pubsub import list_subscriptions
- >>> subscription, next_page_tokens = list_subscriptions() # API request
+ >>> from gcloud import pubsub
+ >>> client = pubsub.Client()
+ >>> subscription, next_page_tokens = client.list_subscriptions() # API request
  >>> [subscription.name for subscription in subscriptions]
  ['subscription_name']
 
 Delete a subscription:
 
 .. doctest::
 
- >>> from gcloud.pubsub import Topic
- >>> from gcloud.pubsub import Subscription
- >>> topic = Topic('topic_name')
- >>> subscription = Subscription('subscription_name', topic)
+ >>> from gcloud import pubsub
+ >>> client = pubsub.Client()
+ >>> topic = client.topic('topic_name')
+ >>> subscription = pubsub.Subscription('subscription_name', topic)
  >>> subscription.delete() # API request
 
 
@@ -213,13 +220,13 @@ Fetch pending messages for a pull subscription:
 
 .. doctest::
 
- >>> from gcloud.pubsub import Topic
- >>> from gcloud.pubsub import Subscription
- >>> topic = Topic('topic_name')
- >>> subscription = Subscription('subscription_name', topic)
- >>> with topic:
- ... topic.publish('this is the first message_payload')
- ... topic.publish('this is the second message_payload',
+ >>> from gcloud import pubsub
+ >>> client = pubsub.Client()
+ >>> topic = client.topic('topic_name')
+ >>> subscription = pubsub.Subscription('subscription_name', topic)
+ >>> 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]
@@ -242,13 +249,13 @@ Fetch a limited number of pending messages for a pull subscription:
 
 .. doctest::
 
- >>> from gcloud.pubsub import Topic
- >>> from gcloud.pubsub import Subscription
- >>> topic = Topic('topic_name')
- >>> subscription = Subscription('subscription_name', topic)
- >>> with topic:
- ... topic.publish('this is the first message_payload')
- ... topic.publish('this is the second message_payload',
+ >>> from gcloud import pubsub
+ >>> client = pubsub.Client()
+ >>> topic = client.topic('topic_name')
+ >>> subscription = pubsub.Subscription('subscription_name', topic)
+ >>> 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]
@@ -258,10 +265,10 @@ Fetch messages for a pull subscription without blocking (none pending):
 
 .. doctest::
 
- >>> from gcloud.pubsub import Topic
- >>> from gcloud.pubsub import Subscription
- >>> topic = Topic('topic_name')
- >>> subscription = Subscription('subscription_name', topic)
+ >>> from gcloud import pubsub
+ >>> client = pubsub.Client()
+ >>> topic = client.topic('topic_name')
+ >>> subscription = pubsub.Subscription('subscription_name', topic)
  >>> received = subscription.pull(max_messages=1) # API request
  >>> messages = [recv[1] for recv in received]
  >>> [message.id for message in messages]