fix!: api consistency between HTTP and Gapic layers (#375)

Author: daniel-sanche

google/cloud/logging_v2/_gapic.py

@@ -49,10 +49,11 @@ def list_entries(
         *,
         filter_=None,
         order_by=None,
+        max_results=None,
         page_size=None,
         page_token=None,
     ):
-        """Return a page of log entry resources.
+        """Return a generator of log entry resources.
 
         Args:
             resource_names (Sequence[str]): Names of one or more parent resources
@@ -69,14 +70,16 @@ def list_entries(
                 https://cloud.google.com/logging/docs/view/advanced_filters
             order_by (str) One of :data:`~logging_v2.ASCENDING`
                 or :data:`~logging_v2.DESCENDING`.
-            page_size (int): maximum number of entries to return, If not passed,
-                defaults to a value set by the API.
-            page_token (str): opaque marker for the next "page" of entries. If not
-                passed, the API will return the first page of
-                entries.
-
+            max_results (Optional[int]):
+                Optional. The maximum number of entries to return.
+                Non-positive values are treated as 0. If None, uses API defaults.
+            page_size (int): number of entries to fetch in each API call. Although
+                requests are paged internally, logs are returned by the generator
+                one at a time. If not passed, defaults to a value set by the API.
+            page_token (str): opaque marker for the starting "page" of entries. If not
+                passed, the API will return the first page of entries.
         Returns:
-            Iterator[~logging_v2.LogEntry]
+            Generator[~logging_v2.LogEntry]
         """
         # full resource names are expected by the API
         resource_names = resource_names
@@ -89,19 +92,27 @@ def list_entries(
         )
 
         response = self._gapic_api.list_log_entries(request=request)
-        page_iter = iter(response)
+        log_iter = iter(response)
 
         # We attach a mutable loggers dictionary so that as Logger
         # objects are created by entry_from_resource, they can be
         # re-used by other log entries from the same logger.
         loggers = {}
 
-        def log_entries_pager(page_iter):
-            for page in page_iter:
-                log_entry_dict = _parse_log_entry(LogEntryPB.pb(page))
+        if max_results is not None and max_results < 0:
+            raise ValueError("max_results must be positive")
+
+        # create generator
+        def log_entries_pager(log_iter):
+            i = 0
+            for entry in log_iter:
+                if max_results is not None and i >= max_results:
+                    break
+                log_entry_dict = _parse_log_entry(LogEntryPB.pb(entry))
                 yield entry_from_resource(log_entry_dict, self._client, loggers=loggers)
+                i += 1
 
-        return log_entries_pager(page_iter)
+        return log_entries_pager(log_iter)
 
     def write_entries(
         self,
@@ -175,7 +186,7 @@ def __init__(self, gapic_api, client):
         self._gapic_api = gapic_api
         self._client = client
 
-    def list_sinks(self, parent, *, page_size=0, page_token=None):
+    def list_sinks(self, parent, *, max_results=None, page_size=None, page_token=None):
         """List sinks for the parent resource.
 
         Args:
@@ -187,27 +198,37 @@ def list_sinks(self, parent, *, page_size=0, page_token=None):
                     "organizations/[ORGANIZATION_ID]"
                     "billingAccounts/[BILLING_ACCOUNT_ID]"
                     "folders/[FOLDER_ID]".
-            page_size (Optional[int]): Maximum number of sinks to return, If not passed,
-                defaults to a value set by the API.
-            page_token (Optional[str]): Opaque marker for the next "page" of sinks. If not
-                passed, the API will return the first page of
-                sinks.
+            max_results (Optional[int]):
+                Optional. The maximum number of entries to return.
+                Non-positive values are treated as 0. If None, uses API defaults.
+            page_size (int): number of entries to fetch in each API call. Although
+                requests are paged internally, logs are returned by the generator
+                one at a time. If not passed, defaults to a value set by the API.
+            page_token (str): opaque marker for the starting "page" of entries. If not
+                passed, the API will return the first page of entries.
 
         Returns:
-            Iterator[~logging_v2.Sink]
+            Generator[~logging_v2.Sink]
         """
         request = ListSinksRequest(
             parent=parent, page_size=page_size, page_token=page_token
         )
         response = self._gapic_api.list_sinks(request)
-        page_iter = iter(response)
+        sink_iter = iter(response)
+
+        if max_results is not None and max_results < 0:
+            raise ValueError("max_results must be positive")
 
-        def sinks_pager(page_iter):
-            for page in page_iter:
+        def sinks_pager(sink_iter):
+            i = 0
+            for entry in sink_iter:
+                if max_results is not None and i >= max_results:
+                    break
                 # Convert the GAPIC sink type into the handwritten `Sink` type
-                yield Sink.from_api_repr(LogSink.to_dict(page), client=self._client)
+                yield Sink.from_api_repr(LogSink.to_dict(entry), client=self._client)
+                i += 1
 
-        return sinks_pager(page_iter)
+        return sinks_pager(sink_iter)
 
     def sink_create(
         self, parent, sink_name, filter_, destination, *, unique_writer_identity=False
@@ -347,33 +368,47 @@ def __init__(self, gapic_api, client):
         self._gapic_api = gapic_api
         self._client = client
 
-    def list_metrics(self, project, *, page_size=0, page_token=None):
+    def list_metrics(
+        self, project, *, max_results=None, page_size=None, page_token=None
+    ):
         """List metrics for the project associated with this client.
 
         Args:
             project (str): ID of the project whose metrics are to be listed.
-            page_size (int): Maximum number of metrics to return, If not passed,
-                defaults to a value set by the API.
-            page_token (str): Opaque marker for the next "page" of metrics. If not
-                passed, the API will return the first page of
-                sinks.
+            max_results (Optional[int]):
+                Optional. The maximum number of entries to return.
+                Non-positive values are treated as 0. If None, uses API defaults.
+            page_size (int): number of entries to fetch in each API call. Although
+                requests are paged internally, logs are returned by the generator
+                one at a time. If not passed, defaults to a value set by the API.
+            page_token (str): opaque marker for the starting "page" of entries. If not
+                passed, the API will return the first page of entries.
 
         Returns:
-            Iterable[logging_v2.Metric]: Iterable of metrics.
+            Generator[logging_v2.Metric]
         """
         path = f"projects/{project}"
         request = ListLogMetricsRequest(
             parent=path, page_size=page_size, page_token=page_token,
         )
         response = self._gapic_api.list_log_metrics(request=request)
-        page_iter = iter(response)
+        metric_iter = iter(response)
+
+        if max_results is not None and max_results < 0:
+            raise ValueError("max_results must be positive")
 
-        def metrics_pager(page_iter):
-            for page in page_iter:
+        def metrics_pager(metric_iter):
+            i = 0
+            for entry in metric_iter:
+                if max_results is not None and i >= max_results:
+                    break
                 # Convert GAPIC metrics type into handwritten `Metric` type
-                yield Metric.from_api_repr(LogMetric.to_dict(page), client=self._client)
+                yield Metric.from_api_repr(
+                    LogMetric.to_dict(entry), client=self._client
+                )
+                i += 1
 
-        return metrics_pager(page_iter)
+        return metrics_pager(metric_iter)
 
     def metric_create(self, project, metric_name, filter_, description):
         """Create a metric resource.

google/cloud/logging_v2/_http.py

@@ -74,6 +74,7 @@ def list_entries(
         *,
         filter_=None,
         order_by=None,
+        max_results=None,
         page_size=None,
         page_token=None,
     ):
@@ -94,14 +95,16 @@ def list_entries(
                 https://cloud.google.com/logging/docs/view/advanced_filters
             order_by (str) One of :data:`~logging_v2.ASCENDING`
                 or :data:`~logging_v2.DESCENDING`.
-            page_size (int): maximum number of entries to return, If not passed,
-                defaults to a value set by the API.
-            page_token (str): opaque marker for the next "page" of entries. If not
-                passed, the API will return the first page of
-                entries.
-
+            max_results (Optional[int]):
+                Optional. The maximum number of entries to return.
+                Non-positive values are treated as 0. If None, uses API defaults.
+            page_size (int): number of entries to fetch in each API call. Although
+                requests are paged internally, logs are returned by the generator
+                one at a time. If not passed, defaults to a value set by the API.
+            page_token (str): opaque marker for the starting "page" of entries. If not
+                passed, the API will return the first page of entries.
         Returns:
-            Iterator[~logging_v2.LogEntry]
+            Generator[~logging_v2.LogEntry]
         """
         extra_params = {"resourceNames": resource_names}
 
@@ -131,7 +134,8 @@ def list_entries(
         )
         # This method uses POST to make a read-only request.
         iterator._HTTP_METHOD = "POST"
-        return iterator
+
+        return _entries_pager(iterator, max_results)
 
     def write_entries(
         self,
@@ -219,7 +223,7 @@ def __init__(self, client):
         self._client = client
         self.api_request = client._connection.api_request
 
-    def list_sinks(self, parent, *, page_size=None, page_token=None):
+    def list_sinks(self, parent, *, max_results=None, page_size=None, page_token=None):
         """List sinks for the parent resource.
 
         See
@@ -234,22 +238,25 @@ def list_sinks(self, parent, *, page_size=None, page_token=None):
                     "organizations/[ORGANIZATION_ID]"
                     "billingAccounts/[BILLING_ACCOUNT_ID]"
                     "folders/[FOLDER_ID]".
-            page_size (Optional[int]): Maximum number of sinks to return, If not passed,
-                defaults to a value set by the API.
-            page_token (Optional[str]): Opaque marker for the next "page" of sinks. If not
-                passed, the API will return the first page of
-                sinks.
+            max_results (Optional[int]):
+                Optional. The maximum number of entries to return.
+                Non-positive values are treated as 0. If None, uses API defaults.
+            page_size (int): number of entries to fetch in each API call. Although
+                requests are paged internally, logs are returned by the generator
+                one at a time. If not passed, defaults to a value set by the API.
+            page_token (str): opaque marker for the starting "page" of entries. If not
+                passed, the API will return the first page of entries.
 
         Returns:
-            Iterator[~logging_v2.Sink]
+            Generator[~logging_v2.Sink]
         """
         extra_params = {}
 
         if page_size is not None:
             extra_params["pageSize"] = page_size
 
         path = f"/{parent}/sinks"
-        return page_iterator.HTTPIterator(
+        iterator = page_iterator.HTTPIterator(
             client=self._client,
             api_request=self._client._connection.api_request,
             path=path,
@@ -259,6 +266,8 @@ def list_sinks(self, parent, *, page_size=None, page_token=None):
             extra_params=extra_params,
         )
 
+        return _entries_pager(iterator, max_results)
+
     def sink_create(
         self, parent, sink_name, filter_, destination, *, unique_writer_identity=False
     ):
@@ -373,32 +382,35 @@ def __init__(self, client):
         self._client = client
         self.api_request = client._connection.api_request
 
-    def list_metrics(self, project, *, page_size=None, page_token=None):
+    def list_metrics(
+        self, project, *, max_results=None, page_size=None, page_token=None
+    ):
         """List metrics for the project associated with this client.
 
         See
         https://cloud.google.com/logging/docs/reference/v2/rest/v2/projects.metrics/list
 
         Args:
-            page_size (Optional[int]): The maximum number of sinks in each
-                page of results from this request. Non-positive values are ignored. Defaults to a
-                sensible value set by the API.
-            page_token (Optional[str]): If present, return the next batch of sinks, using the
-                value, which must correspond to the ``nextPageToken`` value
-                returned in the previous response.  Deprecated: use the ``pages``
-                property ofthe returned iterator instead of manually passing the
-                token.
+            max_results (Optional[int]):
+                Optional. The maximum number of entries to return.
+                Non-positive values are treated as 0. If None, uses API defaults.
+            page_size (int): number of entries to fetch in each API call. Although
+                requests are paged internally, logs are returned by the generator
+                one at a time. If not passed, defaults to a value set by the API.
+            page_token (str): opaque marker for the starting "page" of entries. If not
+                passed, the API will return the first page of entries.
 
         Returns:
-            Iterator[google.cloud.logging_v2.metric.Metric]
+            Generator[logging_v2.Metric]
+
         """
         extra_params = {}
 
         if page_size is not None:
             extra_params["pageSize"] = page_size
 
         path = f"/projects/{project}/metrics"
-        return page_iterator.HTTPIterator(
+        iterator = page_iterator.HTTPIterator(
             client=self._client,
             api_request=self._client._connection.api_request,
             path=path,
@@ -407,6 +419,7 @@ def list_metrics(self, project, *, page_size=None, page_token=None):
             page_token=page_token,
             extra_params=extra_params,
         )
+        return _entries_pager(iterator, max_results)
 
     def metric_create(self, project, metric_name, filter_, description):
         """Create a metric resource.
@@ -469,6 +482,18 @@ def metric_delete(self, project, metric_name):
         self.api_request(method="DELETE", path=target)
 
 
+def _entries_pager(page_iter, max_results=None):
+    if max_results is not None and max_results < 0:
+        raise ValueError("max_results must be positive")
+
+    i = 0
+    for page in page_iter:
+        if max_results is not None and i >= max_results:
+            break
+        yield page
+        i += 1
+
+
 def _item_to_entry(iterator, resource, loggers):
     """Convert a log entry resource to the native object.