Skip to content

Commit ecd0ffc

Browse files
tseavertseaver
committed
Make pubsub example snippets testable.
Toward googleapis#212, googleapis#1141, etc.
1 parent 8a7eea8 commit ecd0ffc

9 files changed

Lines changed: 554 additions & 165 deletions

File tree

‎docs/pubsub-subscription.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,6 @@ Subscriptions
33

44
.. automodule:: gcloud.pubsub.subscription
55
:members:
6+
:member-order: bysource
67
:undoc-members:
78
:show-inheritance:

‎docs/pubsub-topic.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,6 @@ Topics
33

44
.. automodule:: gcloud.pubsub.topic
55
:members:
6+
:member-order: bysource
67
:undoc-members:
78
:show-inheritance:

‎docs/pubsub-usage.rst‎

Lines changed: 73 additions & 161 deletions
Original file line numberDiff line numberDiff line change
@@ -28,229 +28,141 @@ Authentication / Configuration
2828
Manage topics for a project
2929
---------------------------
3030

31-
Create a new topic for the default project:
32-
33-
.. doctest::
34-
35-
>>> from gcloud import pubsub
36-
>>> client = pubsub.Client()
37-
>>> topic = client.topic('topic_name')
38-
>>> topic.create() # API request
39-
40-
Check for the existence of a topic:
31+
List topics for the default project:
4132

42-
.. doctest::
33+
.. literalinclude:: pubsub_snippets.py
34+
:start-after: [START client_list_topics]
35+
:end-before: [END client_list_topics]
4336

44-
>>> from gcloud import pubsub
45-
>>> client = pubsub.Client()
46-
>>> topic = client.topic('topic_name')
47-
>>> topic.exists() # API request
48-
True
37+
Create a new topic for the default project:
4938

50-
List topics for the default project:
39+
.. literalinclude:: pubsub_snippets.py
40+
:start-after: [START topic_create]
41+
:end-before: [END topic_create]
5142

52-
.. doctest::
43+
Check for the existence of a topic:
5344

54-
>>> from gcloud import pubsub
55-
>>> client = pubsub.Client()
56-
>>> topics, next_page_token = client.list_topics() # API request
57-
>>> [topic.name for topic in topics]
58-
['topic_name']
45+
.. literalinclude:: pubsub_snippets.py
46+
:start-after: [START topic_exists]
47+
:end-before: [END topic_exists]
5948

6049
Delete a topic:
6150

62-
.. doctest::
63-
64-
>>> from gcloud import pubsub
65-
>>> client = pubsub.Client()
66-
>>> topic = client.topic('topic_name')
67-
>>> topic.delete() # API request
51+
.. literalinclude:: pubsub_snippets.py
52+
:start-after: [START topic_delete]
53+
:end-before: [END topic_delete]
6854

6955
Fetch the IAM policy for a topic:
7056

71-
.. doctest::
72-
73-
>>> from gcloud import pubsub
74-
>>> client = pubsub.Client()
75-
>>> topic = client.topic('topic_name')
76-
>>> policy = topic.get_iam_policy() # API request
77-
>>> policy.etag
78-
'DEADBEEF'
79-
>>> policy.owners
80-
['user:phred@example.com']
81-
>>> policy.writers
82-
['systemAccount:abc-1234@systemaccounts.example.com']
83-
>>> policy.readers
84-
['domain:example.com']
57+
.. literalinclude:: pubsub_snippets.py
58+
:start-after: [START topic_get_iam_policy]
59+
:end-before: [END topic_get_iam_policy]
8560

8661
Update the IAM policy for a topic:
8762

88-
.. doctest::
89-
90-
>>> from gcloud import pubsub
91-
>>> client = pubsub.Client()
92-
>>> topic = client.topic('topic_name')
93-
>>> policy = topic.get_iam_policy() # API request
94-
>>> policy.writers.add(policy.group('editors-list@example.com'))
95-
>>> topic.set_iam_policy(policy) # API request
63+
.. literalinclude:: pubsub_snippets.py
64+
:start-after: [START topic_set_iam_policy]
65+
:end-before: [END topic_set_iam_policy]
9666

9767
Test permissions allowed by the current IAM policy on a topic:
9868

99-
.. doctest::
100-
101-
>>> from gcloud import pubsub
102-
>>> from gcloud.pubsub.iam import OWNER_ROLE, EDITOR_ROLE, VIEWER_ROLE
103-
>>> client = pubsub.Client()
104-
>>> topic = client.topic('topic_name')
105-
>>> allowed = topic.check_iam_permissions(
106-
... [VIEWER_ROLE, EDITOR_ROLE, OWNER_ROLE]) # API request
107-
>>> allowed == [VIEWER_ROLE, EDITOR_ROLE]
108-
True
69+
.. literalinclude:: pubsub_snippets.py
70+
:start-after: [START topic_check_iam_permissions]
71+
:end-before: [END topic_check_iam_permissions]
10972

11073

11174
Publish messages to a topic
11275
---------------------------
11376

11477
Publish a single message to a topic, without attributes:
11578

116-
.. doctest::
117-
118-
>>> from gcloud import pubsub
119-
>>> client = pubsub.Client()
120-
>>> topic = client.topic('topic_name')
121-
>>> topic.publish('this is the message_payload') # API request
122-
<message_id>
79+
.. literalinclude:: pubsub_snippets.py
80+
:start-after: [START topic_publish_simple_message]
81+
:end-before: [END topic_publish_simple_message]
12382

12483
Publish a single message to a topic, with attributes:
12584

126-
.. doctest::
127-
128-
>>> from gcloud import pubsub
129-
>>> client = pubsub.Client()
130-
>>> topic = client.topic('topic_name')
131-
>>> topic.publish('this is another message_payload',
132-
... attr1='value1', attr2='value2') # API request
133-
<message_id>
85+
.. literalinclude:: pubsub_snippets.py
86+
:start-after: [START topic_publish_message_with_attrs]
87+
:end-before: [END topic_publish_message_with_attrs]
13488

13589
Publish a set of messages to a topic (as a single request):
13690

137-
.. doctest::
138-
139-
>>> from gcloud import pubsub
140-
>>> client = pubsub.Client()
141-
>>> topic = client.topic('topic_name')
142-
>>> with topic.batch() as batch:
143-
... batch.publish('this is the first message_payload')
144-
... batch.publish('this is the second message_payload',
145-
... attr1='value1', attr2='value2')
146-
>>> list(batch)
147-
[<message_id1>, <message_id2>]
91+
.. literalinclude:: pubsub_snippets.py
92+
:start-after: [START topic_batch]
93+
:end-before: [END topic_batch]
14894

14995
.. note::
15096

15197
The only API request happens during the ``__exit__()`` of the topic
152-
used as a context manager.
98+
used as a context manager, and only if the block exits without raising
99+
an exception.
153100

154101

155102
Manage subscriptions to topics
156103
------------------------------
157104

158-
Create a new pull subscription for a topic:
105+
List all subscriptions for the default project:
159106

160107
.. doctest::
161108

162-
>>> from gcloud import pubsub
163-
>>> client = pubsub.Client()
164-
>>> topic = client.topic('topic_name')
165-
>>> subscription = topic.subscription('subscription_name')
166-
>>> subscription.create() # API request
109+
.. literalinclude:: pubsub_snippets.py
110+
:start-after: [START client_list_subscriptions]
111+
:end-before: [END client_list_subscriptions]
167112

168-
Create a new pull subscription for a topic with a non-default ACK deadline:
113+
List subscriptions for a topic:
169114

170-
.. doctest::
115+
.. literalinclude:: pubsub_snippets.py
116+
:start-after: [START topic_list_subscriptions]
117+
:end-before: [END topic_list_subscriptions]
171118

172-
>>> from gcloud import pubsub
173-
>>> client = pubsub.Client()
174-
>>> topic = client.topic('topic_name')
175-
>>> subscription = topic.subscription('subscription_name', ack_deadline=90)
176-
>>> subscription.create() # API request
119+
Create a new pull subscription for a topic, with defaults:
177120

178-
Create a new push subscription for a topic:
121+
.. literalinclude:: pubsub_snippets.py
122+
:start-after: [START topic_subscription_defaults]
123+
:end-before: [END topic_subscription_defaults]
179124

180-
.. doctest::
125+
Create a new pull subscription for a topic with a non-default ACK deadline:
181126

182-
>>> from gcloud import pubsub
183-
>>> ENDPOINT = 'https://example.com/hook'
184-
>>> client = pubsub.Client()
185-
>>> topic = client.topic('topic_name')
186-
>>> subscription = topic.subscription('subscription_name',
187-
... push_endpoint=ENDPOINT)
188-
>>> subscription.create() # API request
127+
.. literalinclude:: pubsub_snippets.py
128+
:start-after: [START topic_subscription_ack90]
129+
:end-before: [END topic_subscription_ack90]
189130

190-
Check for the existence of a subscription:
131+
Create a new push subscription for a topic:
191132

192-
.. doctest::
133+
.. literalinclude:: pubsub_snippets.py
134+
:start-after: [START topic_subscription_push]
135+
:end-before: [END topic_subscription_push]
193136

194-
>>> from gcloud import pubsub
195-
>>> client = pubsub.Client()
196-
>>> topic = client.topic('topic_name')
197-
>>> subscription = topic.subscription('subscription_name')
198-
>>> subscription.exists() # API request
199-
True
137+
Check for the existence of a subscription:
200138

201-
Convert a pull subscription to push:
139+
.. literalinclude:: pubsub_snippets.py
140+
:start-after: [START subscription_exists]
141+
:end-before: [END subscription_exists]
202142

203-
.. doctest::
143+
Convert a pull subscription to push:
204144

205-
>>> from gcloud import pubsub
206-
>>> ENDPOINT = 'https://example.com/hook'
207-
>>> client = pubsub.Client()
208-
>>> topic = client.topic('topic_name')
209-
>>> subscription = topic.subscription('subscription_name')
210-
>>> subscription.modify_push_configuration(push_endpoint=ENDPOINT) # API request
145+
.. literalinclude:: pubsub_snippets.py
146+
:start-after: [START subscription_pull_push]
147+
:end-before: [END subscription_pull_push]
211148

212149
Convert a push subscription to pull:
213150

214-
.. doctest::
215-
216-
>>> from gcloud import pubsub
217-
>>> ENDPOINT = 'https://example.com/hook'
218-
>>> client = pubsub.Client()
219-
>>> topic = client.topic('topic_name')
220-
>>> subscription = topic.subscription('subscription_name',
221-
... push_endpoint=ENDPOINT)
222-
>>> subscription.modify_push_configuration(push_endpoint=None) # API request
223-
224-
List subscriptions for a topic:
225-
226-
.. doctest::
227-
228-
>>> from gcloud import pubsub
229-
>>> client = pubsub.Client()
230-
>>> topic = client.topic('topic_name')
231-
>>> subscriptions, next_page_token = topic.list_subscriptions() # API request
232-
>>> [subscription.name for subscription in subscriptions]
233-
['subscription_name']
234-
235-
List all subscriptions for the default project:
151+
.. literalinclude:: pubsub_snippets.py
152+
:start-after: [START subscription_push_pull]
153+
:end-before: [END subscription_push_pull]
236154

237-
.. doctest::
155+
Re-synchronize a subscription with the back-end:
238156

239-
>>> from gcloud import pubsub
240-
>>> client = pubsub.Client()
241-
>>> subscription, next_page_tokens = client.list_subscriptions() # API request
242-
>>> [subscription.name for subscription in subscriptions]
243-
['subscription_name']
157+
.. literalinclude:: pubsub_snippets.py
158+
:start-after: [START subscription_reload]
159+
:end-before: [END subscription_reload]
244160

245161
Delete a subscription:
246162

247-
.. doctest::
248-
249-
>>> from gcloud import pubsub
250-
>>> client = pubsub.Client()
251-
>>> topic = client.topic('topic_name')
252-
>>> subscription = topic.subscription('subscription_name')
253-
>>> subscription.delete() # API request
163+
.. literalinclude:: pubsub_snippets.py
164+
:start-after: [START subscription_delete]
165+
:end-before: [END subscription_delete]
254166

255167

256168
Pull messages from a subscription

0 commit comments

Comments
 (0)