fix!: [google-cloud-kms] Pagination feature is introduced for method ListKeyHandles in service Autokey

packages/google-cloud-kms/docs/kms_v1/autokey.rst

@@ -4,3 +4,7 @@ Autokey
 .. automodule:: google.cloud.kms_v1.services.autokey
     :members:
     :inherited-members:
+
+.. automodule:: google.cloud.kms_v1.services.autokey.pagers
+    :members:
+    :inherited-members:

packages/google-cloud-kms/google/cloud/kms_v1/services/autokey/async_client.py

@@ -49,6 +49,7 @@
 from google.iam.v1 import policy_pb2  # type: ignore
 from google.longrunning import operations_pb2  # type: ignore
 
+from google.cloud.kms_v1.services.autokey import pagers
 from google.cloud.kms_v1.types import autokey
 
 from .client import AutokeyClient
@@ -57,8 +58,9 @@
 
 
 class AutokeyAsyncClient:
-    """Provides interfaces for using Cloud KMS Autokey to provision new
-    [CryptoKeys][google.cloud.kms.v1.CryptoKey], ready for Customer
+    """Provides interfaces for using `Cloud KMS
+    Autokey <https://cloud.google.com/kms/help/autokey>`__ to provision
+    new [CryptoKeys][google.cloud.kms.v1.CryptoKey], ready for Customer
     Managed Encryption Key (CMEK) use, on-demand. To support certain
     client tooling, this feature is modeled around a
     [KeyHandle][google.cloud.kms.v1.KeyHandle] resource: creating a
@@ -544,7 +546,7 @@ async def list_key_handles(
         retry: OptionalRetry = gapic_v1.method.DEFAULT,
         timeout: Union[float, object] = gapic_v1.method.DEFAULT,
         metadata: Sequence[Tuple[str, str]] = (),
-    ) -> autokey.ListKeyHandlesResponse:
+    ) -> pagers.ListKeyHandlesAsyncPager:
         r"""Lists [KeyHandles][google.cloud.kms.v1.KeyHandle].
 
         .. code-block:: python
@@ -568,10 +570,11 @@ async def sample_list_key_handles():
                 )
 
                 # Make the request
-                response = await client.list_key_handles(request=request)
+                page_result = client.list_key_handles(request=request)
 
                 # Handle the response
-                print(response)
+                async for response in page_result:
+                    print(response)
 
         Args:
             request (Optional[Union[google.cloud.kms_v1.types.ListKeyHandlesRequest, dict]]):
@@ -593,10 +596,13 @@ async def sample_list_key_handles():
                 sent along with the request as metadata.
 
         Returns:
-            google.cloud.kms_v1.types.ListKeyHandlesResponse:
+            google.cloud.kms_v1.services.autokey.pagers.ListKeyHandlesAsyncPager:
                 Response message for
                    [Autokey.ListKeyHandles][google.cloud.kms.v1.Autokey.ListKeyHandles].
 
+                Iterating over this object will yield results and
+                resolve additional pages automatically.
+
         """
         # Create or coerce a protobuf request object.
         # - Quick check: If we got a request object, we should *not* have
@@ -641,6 +647,17 @@ async def sample_list_key_handles():
             metadata=metadata,
         )
 
+        # This method is paged; wrap the response in a pager, which provides
+        # an `__aiter__` convenience method.
+        response = pagers.ListKeyHandlesAsyncPager(
+            method=rpc,
+            request=request,
+            response=response,
+            retry=retry,
+            timeout=timeout,
+            metadata=metadata,
+        )
+
         # Done; return the response.
         return response
 
@@ -855,6 +872,7 @@ async def set_iam_policy(
                 **JSON Example**
 
                 ::
+
                     {
                       "bindings": [
                         {

packages/google-cloud-kms/google/cloud/kms_v1/services/autokey/client.py

@@ -55,6 +55,7 @@
 from google.iam.v1 import policy_pb2  # type: ignore
 from google.longrunning import operations_pb2  # type: ignore
 
+from google.cloud.kms_v1.services.autokey import pagers
 from google.cloud.kms_v1.types import autokey
 
 from .transports.base import DEFAULT_CLIENT_INFO, AutokeyTransport
@@ -99,8 +100,9 @@ def get_transport_class(
 
 
 class AutokeyClient(metaclass=AutokeyClientMeta):
-    """Provides interfaces for using Cloud KMS Autokey to provision new
-    [CryptoKeys][google.cloud.kms.v1.CryptoKey], ready for Customer
+    """Provides interfaces for using `Cloud KMS
+    Autokey <https://cloud.google.com/kms/help/autokey>`__ to provision
+    new [CryptoKeys][google.cloud.kms.v1.CryptoKey], ready for Customer
     Managed Encryption Key (CMEK) use, on-demand. To support certain
     client tooling, this feature is modeled around a
     [KeyHandle][google.cloud.kms.v1.KeyHandle] resource: creating a
@@ -986,7 +988,7 @@ def list_key_handles(
         retry: OptionalRetry = gapic_v1.method.DEFAULT,
         timeout: Union[float, object] = gapic_v1.method.DEFAULT,
         metadata: Sequence[Tuple[str, str]] = (),
-    ) -> autokey.ListKeyHandlesResponse:
+    ) -> pagers.ListKeyHandlesPager:
         r"""Lists [KeyHandles][google.cloud.kms.v1.KeyHandle].
 
         .. code-block:: python
@@ -1010,10 +1012,11 @@ def sample_list_key_handles():
                 )
 
                 # Make the request
-                response = client.list_key_handles(request=request)
+                page_result = client.list_key_handles(request=request)
 
                 # Handle the response
-                print(response)
+                for response in page_result:
+                    print(response)
 
         Args:
             request (Union[google.cloud.kms_v1.types.ListKeyHandlesRequest, dict]):
@@ -1035,10 +1038,13 @@ def sample_list_key_handles():
                 sent along with the request as metadata.
 
         Returns:
-            google.cloud.kms_v1.types.ListKeyHandlesResponse:
+            google.cloud.kms_v1.services.autokey.pagers.ListKeyHandlesPager:
                 Response message for
                    [Autokey.ListKeyHandles][google.cloud.kms.v1.Autokey.ListKeyHandles].
 
+                Iterating over this object will yield results and
+                resolve additional pages automatically.
+
         """
         # Create or coerce a protobuf request object.
         # - Quick check: If we got a request object, we should *not* have
@@ -1080,6 +1086,17 @@ def sample_list_key_handles():
             metadata=metadata,
         )
 
+        # This method is paged; wrap the response in a pager, which provides
+        # an `__iter__` convenience method.
+        response = pagers.ListKeyHandlesPager(
+            method=rpc,
+            request=request,
+            response=response,
+            retry=retry,
+            timeout=timeout,
+            metadata=metadata,
+        )
+
         # Done; return the response.
         return response
 

packages/google-cloud-kms/google/cloud/kms_v1/services/autokey/pagers.py

@@ -0,0 +1,193 @@
+# -*- coding: utf-8 -*-
+# 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.
+#
+from typing import (
+    Any,
+    AsyncIterator,
+    Awaitable,
+    Callable,
+    Iterator,
+    Optional,
+    Sequence,
+    Tuple,
+    Union,
+)
+
+from google.api_core import gapic_v1
+from google.api_core import retry as retries
+from google.api_core import retry_async as retries_async
+
+try:
+    OptionalRetry = Union[retries.Retry, gapic_v1.method._MethodDefault, None]
+    OptionalAsyncRetry = Union[
+        retries_async.AsyncRetry, gapic_v1.method._MethodDefault, None
+    ]
+except AttributeError:  # pragma: NO COVER
+    OptionalRetry = Union[retries.Retry, object, None]  # type: ignore
+    OptionalAsyncRetry = Union[retries_async.AsyncRetry, object, None]  # type: ignore
+
+from google.cloud.kms_v1.types import autokey
+
+
+class ListKeyHandlesPager:
+    """A pager for iterating through ``list_key_handles`` requests.
+
+    This class thinly wraps an initial
+    :class:`google.cloud.kms_v1.types.ListKeyHandlesResponse` object, and
+    provides an ``__iter__`` method to iterate through its
+    ``key_handles`` field.
+
+    If there are more pages, the ``__iter__`` method will make additional
+    ``ListKeyHandles`` requests and continue to iterate
+    through the ``key_handles`` field on the
+    corresponding responses.
+
+    All the usual :class:`google.cloud.kms_v1.types.ListKeyHandlesResponse`
+    attributes are available on the pager. If multiple requests are made, only
+    the most recent response is retained, and thus used for attribute lookup.
+    """
+
+    def __init__(
+        self,
+        method: Callable[..., autokey.ListKeyHandlesResponse],
+        request: autokey.ListKeyHandlesRequest,
+        response: autokey.ListKeyHandlesResponse,
+        *,
+        retry: OptionalRetry = gapic_v1.method.DEFAULT,
+        timeout: Union[float, object] = gapic_v1.method.DEFAULT,
+        metadata: Sequence[Tuple[str, str]] = ()
+    ):
+        """Instantiate the pager.
+
+        Args:
+            method (Callable): The method that was originally called, and
+                which instantiated this pager.
+            request (google.cloud.kms_v1.types.ListKeyHandlesRequest):
+                The initial request object.
+            response (google.cloud.kms_v1.types.ListKeyHandlesResponse):
+                The initial response object.
+            retry (google.api_core.retry.Retry): Designation of what errors,
+                if any, should be retried.
+            timeout (float): The timeout for this request.
+            metadata (Sequence[Tuple[str, str]]): Strings which should be
+                sent along with the request as metadata.
+        """
+        self._method = method
+        self._request = autokey.ListKeyHandlesRequest(request)
+        self._response = response
+        self._retry = retry
+        self._timeout = timeout
+        self._metadata = metadata
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._response, name)
+
+    @property
+    def pages(self) -> Iterator[autokey.ListKeyHandlesResponse]:
+        yield self._response
+        while self._response.next_page_token:
+            self._request.page_token = self._response.next_page_token
+            self._response = self._method(
+                self._request,
+                retry=self._retry,
+                timeout=self._timeout,
+                metadata=self._metadata,
+            )
+            yield self._response
+
+    def __iter__(self) -> Iterator[autokey.KeyHandle]:
+        for page in self.pages:
+            yield from page.key_handles
+
+    def __repr__(self) -> str:
+        return "{0}<{1!r}>".format(self.__class__.__name__, self._response)
+
+
+class ListKeyHandlesAsyncPager:
+    """A pager for iterating through ``list_key_handles`` requests.
+
+    This class thinly wraps an initial
+    :class:`google.cloud.kms_v1.types.ListKeyHandlesResponse` object, and
+    provides an ``__aiter__`` method to iterate through its
+    ``key_handles`` field.
+
+    If there are more pages, the ``__aiter__`` method will make additional
+    ``ListKeyHandles`` requests and continue to iterate
+    through the ``key_handles`` field on the
+    corresponding responses.
+
+    All the usual :class:`google.cloud.kms_v1.types.ListKeyHandlesResponse`
+    attributes are available on the pager. If multiple requests are made, only
+    the most recent response is retained, and thus used for attribute lookup.
+    """
+
+    def __init__(
+        self,
+        method: Callable[..., Awaitable[autokey.ListKeyHandlesResponse]],
+        request: autokey.ListKeyHandlesRequest,
+        response: autokey.ListKeyHandlesResponse,
+        *,
+        retry: OptionalAsyncRetry = gapic_v1.method.DEFAULT,
+        timeout: Union[float, object] = gapic_v1.method.DEFAULT,
+        metadata: Sequence[Tuple[str, str]] = ()
+    ):
+        """Instantiates the pager.
+
+        Args:
+            method (Callable): The method that was originally called, and
+                which instantiated this pager.
+            request (google.cloud.kms_v1.types.ListKeyHandlesRequest):
+                The initial request object.
+            response (google.cloud.kms_v1.types.ListKeyHandlesResponse):
+                The initial response object.
+            retry (google.api_core.retry.AsyncRetry): Designation of what errors,
+                if any, should be retried.
+            timeout (float): The timeout for this request.
+            metadata (Sequence[Tuple[str, str]]): Strings which should be
+                sent along with the request as metadata.
+        """
+        self._method = method
+        self._request = autokey.ListKeyHandlesRequest(request)
+        self._response = response
+        self._retry = retry
+        self._timeout = timeout
+        self._metadata = metadata
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._response, name)
+
+    @property
+    async def pages(self) -> AsyncIterator[autokey.ListKeyHandlesResponse]:
+        yield self._response
+        while self._response.next_page_token:
+            self._request.page_token = self._response.next_page_token
+            self._response = await self._method(
+                self._request,
+                retry=self._retry,
+                timeout=self._timeout,
+                metadata=self._metadata,
+            )
+            yield self._response
+
+    def __aiter__(self) -> AsyncIterator[autokey.KeyHandle]:
+        async def async_generator():
+            async for page in self.pages:
+                for response in page.key_handles:
+                    yield response
+
+        return async_generator()
+
+    def __repr__(self) -> str:
+        return "{0}<{1!r}>".format(self.__class__.__name__, self._response)

packages/google-cloud-kms/google/cloud/kms_v1/services/autokey/transports/grpc.py

@@ -34,8 +34,9 @@
 class AutokeyGrpcTransport(AutokeyTransport):
     """gRPC backend transport for Autokey.
 
-    Provides interfaces for using Cloud KMS Autokey to provision new
-    [CryptoKeys][google.cloud.kms.v1.CryptoKey], ready for Customer
+    Provides interfaces for using `Cloud KMS
+    Autokey <https://cloud.google.com/kms/help/autokey>`__ to provision
+    new [CryptoKeys][google.cloud.kms.v1.CryptoKey], ready for Customer
     Managed Encryption Key (CMEK) use, on-demand. To support certain
     client tooling, this feature is modeled around a
     [KeyHandle][google.cloud.kms.v1.KeyHandle] resource: creating a

packages/google-cloud-kms/google/cloud/kms_v1/services/autokey/transports/grpc_asyncio.py

@@ -37,8 +37,9 @@
 class AutokeyGrpcAsyncIOTransport(AutokeyTransport):
     """gRPC AsyncIO backend transport for Autokey.
 
-    Provides interfaces for using Cloud KMS Autokey to provision new
-    [CryptoKeys][google.cloud.kms.v1.CryptoKey], ready for Customer
+    Provides interfaces for using `Cloud KMS
+    Autokey <https://cloud.google.com/kms/help/autokey>`__ to provision
+    new [CryptoKeys][google.cloud.kms.v1.CryptoKey], ready for Customer
     Managed Encryption Key (CMEK) use, on-demand. To support certain
     client tooling, this feature is modeled around a
     [KeyHandle][google.cloud.kms.v1.KeyHandle] resource: creating a

packages/google-cloud-kms/google/cloud/kms_v1/services/autokey/transports/rest.py

@@ -316,8 +316,9 @@ class AutokeyRestStub:
 class AutokeyRestTransport(AutokeyTransport):
     """REST backend transport for Autokey.
 
-    Provides interfaces for using Cloud KMS Autokey to provision new
-    [CryptoKeys][google.cloud.kms.v1.CryptoKey], ready for Customer
+    Provides interfaces for using `Cloud KMS
+    Autokey <https://cloud.google.com/kms/help/autokey>`__ to provision
+    new [CryptoKeys][google.cloud.kms.v1.CryptoKey], ready for Customer
     Managed Encryption Key (CMEK) use, on-demand. To support certain
     client tooling, this feature is modeled around a
     [KeyHandle][google.cloud.kms.v1.KeyHandle] resource: creating a