feat(storagecontrol): add anywhere cache samples for python

storagecontrol/anywhere_cache_create.py

@@ -0,0 +1,55 @@
+# Copyright 2026 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
+#
+#    https://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_control_create_anywhere_cache]
+from google.cloud import storage_control_v2
+
+
+def create_anywhere_cache(bucket_name: str, zone: str) -> None:
+    # The ID of your GCS bucket
+    # bucket_name = "your-unique-bucket-name"
+
+    # The zone in which to create the Anywhere Cache
+    # zone = "us-central1-a"
+
+    storage_control_client = storage_control_v2.StorageControlClient()
+
+    # The storage bucket path uses the global access pattern, in which the "_"
+    # denotes this bucket exists in the global namespace.
+    bucket_path = (
+        storage_control_client.common_project_path("_") + f"/buckets/{bucket_name}"
+    )
+
+    request = storage_control_v2.CreateAnywhereCacheRequest(
+        parent=bucket_path,
+        anywhere_cache=storage_control_v2.AnywhereCache(
+            zone=zone,
+            admission_policy="admit-on-second-miss",
+        ),
+    )
+    # This operation is long-running. Real-world applications may want to
+    # use callbacks, coroutines, or polling to handle the response.
+    operation = storage_control_client.create_anywhere_cache(request=request)
+    response = operation.result()
+
+    print(f"Created Anywhere Cache: {response.name}")
+
+
+# [END storage_control_create_anywhere_cache]
+
+
+if __name__ == "__main__":
+    create_anywhere_cache(bucket_name=sys.argv[1], zone=sys.argv[2])

storagecontrol/anywhere_cache_disable.py

@@ -0,0 +1,41 @@
+# Copyright 2026 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
+#
+#    https://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_control_disable_anywhere_cache]
+from google.cloud import storage_control_v2
+
+
+def disable_anywhere_cache(anywhere_cache_id: str) -> None:
+    # The full name of the Anywhere Cache
+    # anywhere_cache_id = "projects/_/buckets/bucket-name/anywhereCaches/zone-id"
+
+    storage_control_client = storage_control_v2.StorageControlClient()
+
+    request = storage_control_v2.DisableAnywhereCacheRequest(
+        name=anywhere_cache_id,
+    )
+    # The DisableAnywhereCache RPC returns google.protobuf.Empty,
+    # so we cannot access attributes like .name on the response.
+    storage_control_client.disable_anywhere_cache(request=request)
+
+    print(f"Disabled Anywhere Cache: {anywhere_cache_id}")
+
+
+# [END storage_control_disable_anywhere_cache]
+
+
+if __name__ == "__main__":
+    disable_anywhere_cache(anywhere_cache_id=sys.argv[1])

storagecontrol/anywhere_cache_get.py

@@ -0,0 +1,41 @@
+# Copyright 2026 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
+#
+#    https://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_control_get_anywhere_cache]
+from google.cloud import storage_control_v2
+
+
+def get_anywhere_cache(anywhere_cache_id: str) -> None:
+    # The full name of the Anywhere Cache
+    # anywhere_cache_id = "projects/_/buckets/bucket-name/anywhereCaches/zone-id"
+
+    storage_control_client = storage_control_v2.StorageControlClient()
+
+    request = storage_control_v2.GetAnywhereCacheRequest(
+        name=anywhere_cache_id,
+    )
+    response = storage_control_client.get_anywhere_cache(request=request)
+
+    print(f"Anywhere Cache: {response.name}")
+    print(f"Admission Policy: {response.admission_policy}")
+    print(f"State: {response.state}")
+
+
+# [END storage_control_get_anywhere_cache]
+
+
+if __name__ == "__main__":
+    get_anywhere_cache(anywhere_cache_id=sys.argv[1])

storagecontrol/anywhere_cache_list.py

@@ -0,0 +1,46 @@
+# Copyright 2026 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
+#
+#    https://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_control_list_anywhere_caches]
+from google.cloud import storage_control_v2
+
+
+def list_anywhere_caches(bucket_name: str) -> None:
+    # The ID of your GCS bucket
+    # bucket_name = "your-unique-bucket-name"
+
+    storage_control_client = storage_control_v2.StorageControlClient()
+
+    # The storage bucket path uses the global access pattern, in which the "_"
+    # denotes this bucket exists in the global namespace.
+    bucket_path = (
+        storage_control_client.common_project_path("_") + f"/buckets/{bucket_name}"
+    )
+
+    request = storage_control_v2.ListAnywhereCachesRequest(
+        parent=bucket_path,
+    )
+    page_result = storage_control_client.list_anywhere_caches(request=request)
+
+    for response in page_result:
+        print(f"Anywhere Cache: {response.name}")
+
+
+# [END storage_control_list_anywhere_caches]
+
+
+if __name__ == "__main__":
+    list_anywhere_caches(bucket_name=sys.argv[1])

storagecontrol/anywhere_cache_pause.py

@@ -0,0 +1,40 @@
+# Copyright 2026 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
+#
+#    https://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_control_pause_anywhere_cache]
+from google.cloud import storage_control_v2
+
+
+def pause_anywhere_cache(anywhere_cache_id: str) -> None:
+    # The full name of the Anywhere Cache
+    # anywhere_cache_id = "projects/_/buckets/bucket-name/anywhereCaches/zone-id"
+
+    storage_control_client = storage_control_v2.StorageControlClient()
+
+    request = storage_control_v2.PauseAnywhereCacheRequest(
+        name=anywhere_cache_id,
+    )
+    response = storage_control_client.pause_anywhere_cache(request=request)
+
+    print(f"Paused Anywhere Cache: {response.name}")
+    print(f"State: {response.state}")
+
+
+# [END storage_control_pause_anywhere_cache]
+
+
+if __name__ == "__main__":
+    pause_anywhere_cache(anywhere_cache_id=sys.argv[1])

storagecontrol/anywhere_cache_resume.py

@@ -0,0 +1,40 @@
+# Copyright 2026 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
+#
+#    https://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_control_resume_anywhere_cache]
+from google.cloud import storage_control_v2
+
+
+def resume_anywhere_cache(anywhere_cache_id: str) -> None:
+    # The full name of the Anywhere Cache
+    # anywhere_cache_id = "projects/_/buckets/bucket-name/anywhereCaches/zone-id"
+
+    storage_control_client = storage_control_v2.StorageControlClient()
+
+    request = storage_control_v2.ResumeAnywhereCacheRequest(
+        name=anywhere_cache_id,
+    )
+    response = storage_control_client.resume_anywhere_cache(request=request)
+
+    print(f"Resumed Anywhere Cache: {response.name}")
+    print(f"State: {response.state}")
+
+
+# [END storage_control_resume_anywhere_cache]
+
+
+if __name__ == "__main__":
+    resume_anywhere_cache(anywhere_cache_id=sys.argv[1])

storagecontrol/anywhere_cache_test.py

@@ -0,0 +1,124 @@
+# Copyright 2026 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
+#
+#    https://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 backoff
+from google.api_core import exceptions
+from google.cloud import storage
+
+import pytest
+
+import anywhere_cache_create
+import anywhere_cache_disable
+import anywhere_cache_get
+import anywhere_cache_list
+import anywhere_cache_pause
+import anywhere_cache_resume
+import anywhere_cache_update
+
+
+def test_anywhere_cache_lifecycle(
+    capsys: pytest.CaptureFixture, ubla_enabled_bucket: storage.Bucket
+) -> None:
+    bucket_name = ubla_enabled_bucket.name
+    zone = "us-central1-a"
+    anywhere_cache_id = f"projects/_/buckets/{bucket_name}/anywhereCaches/{zone}"
+
+    # Test create
+    # Creation can be subject to rate limits or transient errors.
+    @backoff.on_exception(backoff.expo, exceptions.GoogleAPICallError, max_tries=3)
+    def do_create() -> None:
+        anywhere_cache_create.create_anywhere_cache(bucket_name=bucket_name, zone=zone)
+
+    do_create()
+    out, _ = capsys.readouterr()
+    assert anywhere_cache_id in out
+
+    # Test get
+    # Use retry to handle eventual consistency.
+    @backoff.on_exception(
+        backoff.expo, (exceptions.NotFound, exceptions.ServiceUnavailable), max_time=120
+    )
+    def do_get() -> None:
+        anywhere_cache_get.get_anywhere_cache(anywhere_cache_id=anywhere_cache_id)
+
+    do_get()
+    out, _ = capsys.readouterr()
+    assert anywhere_cache_id in out
+    assert "admit-on-second-miss" in out
+
+    # Test list
+    # Use retry to handle eventual consistency.
+    @backoff.on_exception(
+        backoff.expo, (exceptions.NotFound, exceptions.ServiceUnavailable), max_time=120
+    )
+    def do_list() -> None:
+        anywhere_cache_list.list_anywhere_caches(bucket_name=bucket_name)
+
+    do_list()
+    out, _ = capsys.readouterr()
+    assert anywhere_cache_id in out
+
+    # Test update
+    # Use retry to handle eventual consistency.
+    @backoff.on_exception(
+        backoff.expo, (exceptions.NotFound, exceptions.ServiceUnavailable), max_time=120
+    )
+    def do_update() -> None:
+        # Update to a different policy to verify the change.
+        anywhere_cache_update.update_anywhere_cache(
+            anywhere_cache_id=anywhere_cache_id, admission_policy="admit-on-first-miss"
+        )
+
+    do_update()
+    out, _ = capsys.readouterr()
+    assert anywhere_cache_id in out
+    assert "admit-on-first-miss" in out
+
+    # Test pause
+    # Use retry to handle eventual consistency.
+    @backoff.on_exception(
+        backoff.expo, (exceptions.NotFound, exceptions.ServiceUnavailable), max_time=120
+    )
+    def do_pause() -> None:
+        anywhere_cache_pause.pause_anywhere_cache(anywhere_cache_id=anywhere_cache_id)
+
+    do_pause()
+    out, _ = capsys.readouterr()
+    assert anywhere_cache_id in out
+
+    # Test resume
+    # Use retry to handle eventual consistency.
+    @backoff.on_exception(
+        backoff.expo, (exceptions.NotFound, exceptions.ServiceUnavailable), max_time=120
+    )
+    def do_resume() -> None:
+        anywhere_cache_resume.resume_anywhere_cache(anywhere_cache_id=anywhere_cache_id)
+
+    do_resume()
+    out, _ = capsys.readouterr()
+    assert anywhere_cache_id in out
+
+    # Test disable
+    # Use retry to handle eventual consistency.
+    @backoff.on_exception(
+        backoff.expo, (exceptions.NotFound, exceptions.ServiceUnavailable), max_time=120
+    )
+    def do_disable() -> None:
+        anywhere_cache_disable.disable_anywhere_cache(
+            anywhere_cache_id=anywhere_cache_id
+        )
+
+    do_disable()
+    out, _ = capsys.readouterr()
+    assert anywhere_cache_id in out