samples: add pubsub notifications samples (#646)

* samples: add sample list notifications

* samples: add sample get notification

* add tests for get list notifications samples

* add sample and test for creating a pubsub notification

* add sample for deleting a pubsub notification

* revise notification samples tests

* update samples readme

* clean up pubsub topic in tests

* revise readme per comment

Author: cojenco

samples/README.md

@@ -65,10 +65,12 @@ for instructions on setting up credentials for applications.
 * [CORS Configuration](#cors-configuration)
 * [Create Bucket](#create-bucket)
 * [Create Bucket Class Location](#create-bucket-class-location)
+* [Create Bucket Notifications](#create-bucket-notifications)
 * [Create HMAC Key](#create-hmac-key)
 * [Deactivate HMAC Key](#deactivate-hmac-key)
 * [Define Bucket Website Configuration](#define-bucket-website-configuration)
 * [Delete Bucket](#delete-bucket)
+* [Delete Bucket Notification](#delete-bucket-notification)
 * [Delete File](#delete-file)
 * [Delete File Archived Generation](#delete-file-archived-generation)
 * [Delete HMAC Key](#delete-hmac-key)
@@ -104,6 +106,7 @@ for instructions on setting up credentials for applications.
 * [Get Service Account](#get-service-account)
 * [Get Uniform Bucket Level Access](#get-uniform-bucket-level-access)
 * [List Buckets](#list-buckets)
+* [List Bucket Notifications](#list-bucket-notifications)
 * [List File Archived Generations](#list-file-archived-generations)
 * [List Files](#list-files)
 * [List Files With Prefix](#list-files-with-prefix)
@@ -117,6 +120,7 @@ for instructions on setting up credentials for applications.
 * [Print Bucket ACL For User](#print-bucket-acl-for-user)
 * [Print File ACL](#print-file-acl)
 * [Print File ACL For User](#print-file-acl-for-user)
+* [Print PubSub Bucket Notification](#print-pubsub-bucket-notification)
 * [Release Event Based Hold](#release-event-based-hold)
 * [Release Temporary Hold](#release-temporary-hold)
 * [Remove Bucket Conditional IAM Binding](#remove-bucket-conditional-iam-binding)
@@ -299,6 +303,15 @@ View the [source code](https://github.com/googleapis/python-storage/blob/main/sa
 
 `python storage_create_bucket_class_location.py`
 
+-----
+### Create Bucket Notifications
+[![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/python-storage&page=editor&open_in_editor=samples/snippets/storage_create_bucket_notifications.py,samples/README.md)
+
+View the [source code](https://github.com/googleapis/python-storage/blob/main/samples/snippets/storage_create_bucket_notifications.py). To run this sample:
+
+
+`python storage_create_bucket_notifications.py <BUCKET_NAME> <TOPIC_NAME>`
+
 -----
 ### Create HMAC Key
 [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/python-storage&page=editor&open_in_editor=samples/snippets/storage_create_hmac_key.py,samples/README.md)
@@ -335,6 +348,15 @@ View the [source code](https://github.com/googleapis/python-storage/blob/main/sa
 
 `python storage_delete_bucket.py`
 
+-----
+### Delete Bucket Notification
+[![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/python-storage&page=editor&open_in_editor=samples/snippets/storage_delete_bucket_notification.py,samples/README.md)
+
+View the [source code](https://github.com/googleapis/python-storage/blob/main/samples/snippets/storage_delete_bucket_notification.py). To run this sample:
+
+
+`python storage_delete_bucket_notification.py <BUCKET_NAME> <NOTIFICATION_ID>`
+
 -----
 ### Delete File
 [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/python-storage&page=editor&open_in_editor=samples/snippets/storage_delete_file.py,samples/README.md)
@@ -648,6 +670,15 @@ View the [source code](https://github.com/googleapis/python-storage/blob/main/sa
 
 `python storage_list_buckets.py`
 
+-----
+### List Bucket Notifications
+[![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/python-storage&page=editor&open_in_editor=samples/snippets/storage_list_bucket_notifications.py,samples/README.md)
+
+View the [source code](https://github.com/googleapis/python-storage/blob/main/samples/snippets/storage_list_bucket_notifications.py). To run this sample:
+
+
+`python storage_list_bucket_notifications.py <BUCKET_NAME>`
+
 -----
 ### List File Archived Generations
 [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/python-storage&page=editor&open_in_editor=samples/snippets/storage_list_file_archived_generations.py,samples/README.md)
@@ -765,6 +796,15 @@ View the [source code](https://github.com/googleapis/python-storage/blob/main/sa
 
 `python storage_print_file_acl_for_user.py`
 
+-----
+### Print PubSub Bucket Notification
+[![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/python-storage&page=editor&open_in_editor=samples/snippets/storage_print_pubsub_bucket_notification.py,samples/README.md)
+
+View the [source code](https://github.com/googleapis/python-storage/blob/main/samples/snippets/storage_print_pubsub_bucket_notification.py). To run this sample:
+
+
+`python storage_print_pubsub_bucket_notification.py <BUCKET_NAME> <NOTIFICATION_ID>`
+
 -----
 ### Release Event Based Hold
 [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/python-storage&page=editor&open_in_editor=samples/snippets/storage_release_event_based_hold.py,samples/README.md)

samples/snippets/notification_test.py

@@ -0,0 +1,120 @@
+# Copyright 2021 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+import uuid
+
+from google.api_core.exceptions import NotFound
+from google.cloud import storage
+
+import pytest
+
+import storage_create_bucket_notifications
+import storage_delete_bucket_notification
+import storage_list_bucket_notifications
+import storage_print_pubsub_bucket_notification
+
+_topic_name = f"notification-{uuid.uuid4()}"
+
+
+@pytest.fixture(scope="module")
+def storage_client():
+    return storage.Client()
+
+
+@pytest.fixture(scope="module")
+def publisher_client():
+    try:
+        from google.cloud.pubsub_v1 import PublisherClient
+    except ImportError:
+        pytest.skip("Cannot import pubsub")
+
+    return PublisherClient()
+
+
+@pytest.fixture(scope="module")
+def _notification_topic(storage_client, publisher_client):
+    topic_path = publisher_client.topic_path(storage_client.project, _topic_name)
+    try:
+        topic = publisher_client.get_topic(request={"topic": topic_path})
+    except NotFound:
+        topic = publisher_client.create_topic(request={"name": topic_path})
+
+    policy = publisher_client.get_iam_policy(request={"resource": topic_path})
+    binding = policy.bindings.add()
+    binding.role = "roles/pubsub.publisher"
+    binding.members.append(
+        "serviceAccount:{}".format(storage_client.get_service_account_email())
+    )
+    publisher_client.set_iam_policy(request={"resource": topic_path, "policy": policy})
+
+    yield topic
+
+    try:
+        publisher_client.delete_topic(request={"topic": topic.name})
+    except NotFound:
+        pass
+
+
+@pytest.fixture(scope="module")
+def bucket_w_notification(storage_client, _notification_topic):
+    """Yields a bucket with notification that is deleted after the tests complete."""
+    bucket = None
+    while bucket is None or bucket.exists():
+        bucket_name = f"notification-test-{uuid.uuid4()}"
+        bucket = storage_client.bucket(bucket_name)
+    bucket.create()
+
+    notification = bucket.notification(topic_name=_topic_name)
+    notification.create()
+
+    yield bucket
+
+    bucket.delete(force=True)
+
+
+def test_list_bucket_notifications(bucket_w_notification, capsys):
+    storage_list_bucket_notifications.list_bucket_notifications(bucket_w_notification.name)
+    out, _ = capsys.readouterr()
+    assert "Notification ID" in out
+
+
+def test_print_pubsub_bucket_notification(bucket_w_notification, capsys):
+    notification_id = 1
+    storage_print_pubsub_bucket_notification.print_pubsub_bucket_notification(bucket_w_notification.name, notification_id)
+    out, _ = capsys.readouterr()
+    assert "Notification ID: 1" in out
+
+
+def test_create_bucket_notifications(bucket_w_notification, capsys):
+    # test only bucket notification ID 1 was created in the fixture
+    assert bucket_w_notification.notification(notification_id=1).exists() is True
+    assert bucket_w_notification.notification(notification_id=2).exists() is False
+
+    storage_create_bucket_notifications.create_bucket_notifications(bucket_w_notification.name, _topic_name)
+    out, _ = capsys.readouterr()
+    assert "Successfully created notification" in out
+    # test succesfully creates new bucket notification with ID 2
+    assert bucket_w_notification.notification(notification_id=2).exists() is True
+
+
+def test_delete_bucket_notification(bucket_w_notification, capsys):
+    # test bucket notification ID 1 was created in the fixture
+    notification_id = 1
+    assert bucket_w_notification.notification(notification_id=notification_id).exists() is True
+
+    storage_delete_bucket_notification.delete_bucket_notification(bucket_w_notification.name, notification_id)
+    out, _ = capsys.readouterr()
+    assert "Successfully deleted notification" in out
+    assert bucket_w_notification.notification(notification_id=notification_id).exists() is False

samples/snippets/storage_create_bucket_notifications.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python
+
+# Copyright 2021 Google LLC. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the 'License');
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import sys
+
+"""Sample that creates a notification configuration for a bucket.
+This sample is used on this page:
+    https://cloud.google.com/storage/docs/reporting-changes
+For more information, see README.md.
+"""
+
+# [START storage_create_bucket_notifications]
+from google.cloud import storage
+
+
+def create_bucket_notifications(bucket_name, topic_name):
+    """Creates a notification configuration for a bucket."""
+    # The ID of your GCS bucket
+    # bucket_name = "your-bucket-name"
+    # The name of a topic
+    # topic_name = "your-topic-name"
+
+    storage_client = storage.Client()
+    bucket = storage_client.bucket(bucket_name)
+    notification = bucket.notification(topic_name=topic_name)
+    notification.create()
+
+    print(f"Successfully created notification with ID {notification.notification_id} for bucket {bucket_name}")
+
+# [END storage_create_bucket_notifications]
+
+
+if __name__ == "__main__":
+    create_bucket_notifications(bucket_name=sys.argv[1], topic_name=sys.argv[2])

samples/snippets/storage_delete_bucket_notification.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python
+
+# Copyright 2021 Google LLC. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the 'License');
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import sys
+
+"""Sample that deletes a notification configuration for a bucket.
+This sample is used on this page:
+    https://cloud.google.com/storage/docs/reporting-changes
+For more information, see README.md.
+"""
+
+# [START storage_delete_bucket_notification]
+from google.cloud import storage
+
+
+def delete_bucket_notification(bucket_name, notification_id):
+    """Deletes a notification configuration for a bucket."""
+    # The ID of your GCS bucket
+    # bucket_name = "your-bucket-name"
+    # The ID of the notification
+    # notification_id = "your-notification-id"
+
+    storage_client = storage.Client()
+    bucket = storage_client.bucket(bucket_name)
+    notification = bucket.notification(notification_id=notification_id)
+    notification.delete()
+
+    print(f"Successfully deleted notification with ID {notification_id} for bucket {bucket_name}")
+
+# [END storage_delete_bucket_notification]
+
+
+if __name__ == "__main__":
+    delete_bucket_notification(bucket_name=sys.argv[1], notification_id=sys.argv[2])

samples/snippets/storage_list_bucket_notifications.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python
+
+# Copyright 2021 Google LLC. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the 'License');
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import sys
+
+"""Sample that lists notification configurations for a bucket.
+This sample is used on this page:
+    https://cloud.google.com/storage/docs/reporting-changes
+For more information, see README.md.
+"""
+
+# [START storage_list_bucket_notifications]
+from google.cloud import storage
+
+
+def list_bucket_notifications(bucket_name):
+    """Lists notification configurations for a bucket."""
+    # The ID of your GCS bucket
+    # bucket_name = "your-bucket-name"
+
+    storage_client = storage.Client()
+    bucket = storage_client.bucket(bucket_name)
+    notifications = bucket.list_notifications()
+
+    for notification in notifications:
+        print(f"Notification ID: {notification.notification_id}")
+
+# [END storage_list_bucket_notifications]
+
+
+if __name__ == "__main__":
+    list_bucket_notifications(bucket_name=sys.argv[1])