samples: add samples for object retention (#1247)

Author: cojenco

samples/snippets/snippets_test.py

@@ -37,6 +37,7 @@
 import storage_cors_configuration
 import storage_create_bucket_class_location
 import storage_create_bucket_dual_region
+import storage_create_bucket_object_retention
 import storage_define_bucket_website_configuration
 import storage_delete_file
 import storage_delete_file_archived_generation
@@ -71,6 +72,7 @@
 import storage_set_autoclass
 import storage_set_bucket_default_kms_key
 import storage_set_client_endpoint
+import storage_set_object_retention_policy
 import storage_set_metadata
 import storage_transfer_manager_download_bucket
 import storage_transfer_manager_download_chunks_concurrently
@@ -818,3 +820,24 @@ def test_transfer_manager_upload_chunks_concurrently(test_bucket, capsys):
 
         out, _ = capsys.readouterr()
         assert "File {} uploaded to {}".format(file.name, BLOB_NAME) in out
+
+
+def test_object_retention_policy(test_bucket_create, capsys):
+    storage_create_bucket_object_retention.create_bucket_object_retention(
+        test_bucket_create.name
+    )
+    out, _ = capsys.readouterr()
+    assert f"Created bucket {test_bucket_create.name} with object retention enabled setting" in out
+
+    blob_name = "test_object_retention"
+    storage_set_object_retention_policy.set_object_retention_policy(
+        test_bucket_create.name, "hello world", blob_name
+    )
+    out, _ = capsys.readouterr()
+    assert f"Retention policy for file {blob_name}" in out
+
+    # Remove retention policy for test cleanup
+    blob = test_bucket_create.blob(blob_name)
+    blob.retention.mode = None
+    blob.retention.retain_until_time = None
+    blob.patch(override_unlocked_retention=True)

samples/snippets/storage_create_bucket_object_retention.py

@@ -0,0 +1,38 @@
+#!/usr/bin/env python
+
+# Copyright 2024 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 sys
+
+# [START storage_create_bucket_with_object_retention]
+from google.cloud import storage
+
+
+def create_bucket_object_retention(bucket_name):
+    """Creates a bucket with object retention enabled."""
+    # The ID of your GCS bucket
+    # bucket_name = "your-bucket-name"
+
+    storage_client = storage.Client()
+    bucket = storage_client.create_bucket(bucket_name, enable_object_retention=True)
+
+    print(f"Created bucket {bucket_name} with object retention enabled setting: {bucket.object_retention_mode}")
+
+
+# [END storage_create_bucket_with_object_retention]
+
+
+if __name__ == "__main__":
+    create_bucket_object_retention(bucket_name=sys.argv[1])

samples/snippets/storage_get_bucket_metadata.py

@@ -44,6 +44,7 @@ def bucket_metadata(bucket_name):
     print(f"Retention Effective Time: {bucket.retention_policy_effective_time}")
     print(f"Retention Period: {bucket.retention_period}")
     print(f"Retention Policy Locked: {bucket.retention_policy_locked}")
+    print(f"Object Retention Mode: {bucket.object_retention_mode}")
     print(f"Requester Pays: {bucket.requester_pays}")
     print(f"Self Link: {bucket.self_link}")
     print(f"Time Created: {bucket.time_created}")

samples/snippets/storage_get_metadata.py

@@ -59,6 +59,8 @@ def blob_metadata(bucket_name, blob_name):
         "Event based hold: ",
         "enabled" if blob.event_based_hold else "disabled",
     )
+    print(f"Retention mode: {blob.retention.mode}")
+    print(f"Retention retain until time: {blob.retention.retain_until_time}")
     if blob.retention_expiration_time:
         print(
             f"retentionExpirationTime: {blob.retention_expiration_time}"

samples/snippets/storage_set_object_retention_policy.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python
+
+# Copyright 2024 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 datetime
+import sys
+
+# [START storage_set_object_retention_policy]
+from google.cloud import storage
+
+
+def set_object_retention_policy(bucket_name, contents, destination_blob_name):
+    """Set the object retention policy of a file."""
+
+    # The ID of your GCS bucket
+    # bucket_name = "your-bucket-name"
+
+    # The contents to upload to the file
+    # contents = "these are my contents"
+
+    # The ID of your GCS object
+    # destination_blob_name = "storage-object-name"
+
+    storage_client = storage.Client()
+    bucket = storage_client.bucket(bucket_name)
+    blob = bucket.blob(destination_blob_name)
+    blob.upload_from_string(contents)
+
+    # Set the retention policy for the file.
+    blob.retention.mode = "Unlocked"
+    retention_date = datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(days=10)
+    blob.retention.retain_until_time = retention_date
+    blob.patch()
+    print(
+        f"Retention policy for file {destination_blob_name} was set to: {blob.retention.mode}."
+    )
+
+    # To modify an existing policy on an unlocked file object, pass in the override parameter.
+    new_retention_date = datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(days=9)
+    blob.retention.retain_until_time = new_retention_date
+    blob.patch(override_unlocked_retention=True)
+    print(
+        f"Retention policy for file {destination_blob_name} was updated to: {blob.retention.retain_until_time}."
+    )
+
+
+# [END storage_set_object_retention_policy]
+
+
+if __name__ == "__main__":
+    set_object_retention_policy(
+        bucket_name=sys.argv[1],
+        contents=sys.argv[2],
+        destination_blob_name=sys.argv[3],
+    )