Snippets for Subscription IAM methods.

Author: tseaver

docs/pubsub-usage.rst

@@ -195,44 +195,18 @@ Update the acknowlegement deadline for pulled messages:
 
 Fetch the IAM policy for a subscription
 
-.. doctest::
-
-   >>> from gcloud import pubsub
-   >>> client = pubsub.Client()
-   >>> topic = client.topic('topic_name')
-   >>> subscription = topic.subscription('subscription_name')
-   >>> policy = subscription.get_iam_policy()  # API request
-   >>> policy.etag
-   'DEADBEEF'
-   >>> policy.owners
-   ['user:phred@example.com']
-   >>> policy.writers
-   ['systemAccount:abc-1234@systemaccounts.example.com']
-   >>> policy.readers
-   ['domain:example.com']
+.. literalinclude:: pubsub_snippets.py
+   :start-after: [START subscription_get_iam_policy]
+   :end-before: [END subscription_get_iam_policy]
 
 Update the IAM policy for a subscription:
 
-.. doctest::
-
-   >>> from gcloud import pubsub
-   >>> client = pubsub.Client()
-   >>> topic = client.topic('topic_name')
-   >>> subscription = topic.subscription('subscription_name')
-   >>> policy = subscription.get_iam_policy()  # API request
-   >>> policy.writers.add(policy.group('editors-list@example.com'))
-   >>> subscription.set_iam_policy(policy)  # API request
+.. literalinclude:: pubsub_snippets.py
+   :start-after: [START subscription_set_iam_policy]
+   :end-before: [END subscription_set_iam_policy]
 
 Test permissions allowed by the current IAM policy on a subscription:
 
-.. doctest::
-
-   >>> from gcloud import pubsub
-   >>> from gcloud.pubsub.iam import OWNER_ROLE, EDITOR_ROLE, VIEWER_ROLE
-   >>> client = pubsub.Client()
-   >>> topic = client.topic('topic_name')
-   >>> subscription = topic.subscription('subscription_name')
-   >>> allowed = subscription.check_iam_permissions(
-   ...     [VIEWER_ROLE, EDITOR_ROLE, OWNER_ROLE])  # API request
-   >>> allowed == [VIEWER_ROLE, EDITOR_ROLE]
-   True
+.. literalinclude:: pubsub_snippets.py
+   :start-after: [START subscription_check_iam_permissions]
+   :end-before: [END subscription_check_iam_permissions]

docs/pubsub_snippets.py

@@ -131,20 +131,22 @@ def topic_iam_policy(client, to_delete):
 
     # [START topic_get_iam_policy]
     policy = topic.get_iam_policy()             # API request
+    # [END topic_get_iam_policy]
+
     assert len(policy.viewers) == 0
     assert len(policy.editors) == 0
     assert len(policy.owners) == 0
-    # [END topic_get_iam_policy]
 
     # [START topic_set_iam_policy]
     ALL_USERS = policy.all_users()
     policy.viewers.add(ALL_USERS)
     LOGS_GROUP = policy.group('cloud-logs@google.com')
     policy.editors.add(LOGS_GROUP)
     new_policy = topic.set_iam_policy(policy)   # API request
+    # [END topic_set_iam_policy]
+
     assert ALL_USERS in new_policy.viewers
     assert LOGS_GROUP in new_policy.editors
-    # [END topic_set_iam_policy]
 
 
 # @snippet   # Disabled due to #1687
@@ -363,6 +365,60 @@ def log_exception(_):
         (extras,))
 
 
+@snippet
+def subscription_iam_policy(client, to_delete):
+    """Fetch / set a subscription's IAM policy."""
+    TOPIC_NAME = 'subscription_iam_policy-%d' % (_millis(),)
+    SUB_NAME = 'subscription_iam_policy-defaults-%d' % (_millis(),)
+    topic = client.topic(TOPIC_NAME)
+    topic.create()
+    to_delete.append(topic)
+
+    subscription = topic.subscription(SUB_NAME)
+    subscription.create()
+    to_delete.append(subscription)
+
+    # [START subscription_get_iam_policy]
+    policy = subscription.get_iam_policy()             # API request
+    # [END subscription_get_iam_policy]
+
+    assert len(policy.viewers) == 0
+    assert len(policy.editors) == 0
+    assert len(policy.owners) == 0
+
+    # [START subscription_set_iam_policy]
+    ALL_USERS = policy.all_users()
+    policy.viewers.add(ALL_USERS)
+    LOGS_GROUP = policy.group('cloud-logs@google.com')
+    policy.editors.add(LOGS_GROUP)
+    new_policy = subscription.set_iam_policy(policy)   # API request
+    # [END subscription_set_iam_policy]
+
+    assert ALL_USERS in new_policy.viewers
+    assert LOGS_GROUP in new_policy.editors
+
+
+# @snippet   # Disabled due to #1687
+def subscription_check_iam_permissions(client, to_delete):
+    """Check subscription IAM permissions."""
+    TOPIC_NAME = 'subscription_check_iam_permissions-%d' % (_millis(),)
+    SUB_NAME = 'subscription_check_iam_permissions-defaults-%d' % (_millis(),)
+    topic = client.topic(TOPIC_NAME)
+    topic.create()
+    to_delete.append(topic)
+
+    subscription = topic.subscription(SUB_NAME)
+    subscription.create()
+    to_delete.append(subscription)
+
+    # [START subscription_check_iam_permissions]
+    from gcloud.pubsub.iam import OWNER_ROLE, EDITOR_ROLE, VIEWER_ROLE
+    TO_CHECK = [OWNER_ROLE, EDITOR_ROLE, VIEWER_ROLE]
+    ALLOWED = subscription.check_iam_permissions(TO_CHECK)
+    assert set(ALLOWED) == set(TO_CHECK)
+    # [END subscription_check_iam_permissions]
+
+
 def _find_examples():
     funcs = [obj for obj in globals().values()
              if getattr(obj, '_snippet', False)]

gcloud/pubsub/subscription.py

@@ -338,6 +338,12 @@ def get_iam_policy(self, client=None):
         See:
         https://cloud.google.com/pubsub/reference/rest/v1/projects.subscriptions/getIamPolicy
 
+        Example:
+
+        .. literalinclude:: pubsub_snippets.py
+           :start-after: [START subscription_get_iam_policy]
+           :end-before: [END subscription_get_iam_policy]
+
         :type client: :class:`gcloud.pubsub.client.Client` or ``NoneType``
         :param client: the client to use.  If not passed, falls back to the
                        ``client`` stored on the current subscription's topic.
@@ -356,6 +362,12 @@ def set_iam_policy(self, policy, client=None):
         See:
         https://cloud.google.com/pubsub/reference/rest/v1/projects.subscriptions/setIamPolicy
 
+        Example:
+
+        .. literalinclude:: pubsub_snippets.py
+           :start-after: [START subscription_set_iam_policy]
+           :end-before: [END subscription_set_iam_policy]
+
         :type policy: :class:`gcloud.pubsub.iam.Policy`
         :param policy: the new policy, typically fetched via
                        :meth:`get_iam_policy` and updated in place.
@@ -379,6 +391,12 @@ def check_iam_permissions(self, permissions, client=None):
         See:
         https://cloud.google.com/pubsub/reference/rest/v1/projects.subscriptions/testIamPermissions
 
+        Example:
+
+        .. literalinclude:: pubsub_snippets.py
+           :start-after: [START subscription_check_iam_permissions]
+           :end-before: [END subscription_check_iam_permissions]
+
         :type permissions: list of string
         :param permissions: list of permissions to be tested