Skip to content

Commit ff05ac3

Browse files
tseavertseaver
authored
Docs/fixit: normalize docs for 'page_size' / 'max_results' / 'page_token' (#6842)
1 parent f880e4e commit ff05ac3

File tree

14 files changed

+135
-61
lines changed

14 files changed

+135
-61
lines changed

‎bigquery/google/cloud/bigquery/client.py‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1674,8 +1674,9 @@ def list_rows(
16741674
start_index (int):
16751675
(Optional) The zero-based index of the starting row to read.
16761676
page_size (int):
1677-
(Optional) The maximum number of items to return per page in
1678-
the iterator.
1677+
Optional. The maximum number of rows in each page of results
1678+
from this request. Non-positive values are ignored. Defaults
1679+
to a sensible value set by the API.
16791680
retry (:class:`google.api_core.retry.Retry`):
16801681
(Optional) How to retry the RPC.
16811682

‎bigquery/google/cloud/bigquery/table.py‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1240,7 +1240,9 @@ class RowIterator(HTTPIterator):
12401240
page_token (str): A token identifying a page in a result set to start
12411241
fetching results from.
12421242
max_results (int, optional): The maximum number of results to fetch.
1243-
page_size (int, optional): The number of items to return per page.
1243+
page_size (int, optional): The maximum number of rows in each page
1244+
of results from this request. Non-positive values are ignored.
1245+
Defaults to a sensible value set by the API.
12441246
extra_params (Dict[str, object]):
12451247
Extra query string parameters for the API call.
12461248
table (Union[ \

‎dns/google/cloud/dns/client.py‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -82,9 +82,11 @@ def list_zones(self, max_results=None, page_token=None):
8282
passed, defaults to a value set by the API.
8383
8484
:type page_token: str
85-
:param page_token: opaque marker for the next "page" of zones. If
86-
not passed, the API will return the first page of
87-
zones.
85+
:param page_token: Optional. If present, return the next batch of
86+
zones, using the value, which must correspond to the
87+
``nextPageToken`` value returned in the previous response.
88+
Deprecated: use the ``pages`` property of the returned iterator
89+
instead of manually passing the token.
8890
8991
:rtype: :class:`~google.api_core.page_iterator.Iterator`
9092
:returns: Iterator of :class:`~google.cloud.dns.zone.ManagedZone`

‎dns/google/cloud/dns/zone.py‎

Lines changed: 15 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -325,13 +325,16 @@ def list_resource_record_sets(self, max_results=None, page_token=None, client=No
325325
https://cloud.google.com/dns/api/v1/resourceRecordSets/list
326326
327327
:type max_results: int
328-
:param max_results: maximum number of zones to return, If not
329-
passed, defaults to a value set by the API.
328+
:param max_results: Optional. The maximum number of resource record
329+
sets to return. Defaults to a sensible value
330+
set by the API.
330331
331332
:type page_token: str
332-
:param page_token: opaque marker for the next "page" of zones. If
333-
not passed, the API will return the first page of
334-
zones.
333+
:param page_token: Optional. If present, return the next batch of
334+
resource record sets, using the value, which must correspond to
335+
the ``nextPageToken`` value returned in the previous response.
336+
Deprecated: use the ``pages`` property of the returned iterator
337+
instead of manually passing the token.
335338
336339
:type client: :class:`google.cloud.dns.client.Client`
337340
:param client:
@@ -363,13 +366,15 @@ def list_changes(self, max_results=None, page_token=None, client=None):
363366
https://cloud.google.com/dns/api/v1/resourceRecordSets/list
364367
365368
:type max_results: int
366-
:param max_results: maximum number of zones to return, If not
367-
passed, defaults to a value set by the API.
369+
:param max_results: Optional. The maximum number of change sets
370+
to return. Defaults to a sensible value set by the API.
368371
369372
:type page_token: str
370-
:param page_token: opaque marker for the next "page" of zones. If
371-
not passed, the API will return the first page of
372-
zones.
373+
:param page_token: Optional. If present, return the next batch of
374+
change sets, using the value, which must correspond to the
375+
``nextPageToken`` value returned in the previous response.
376+
Deprecated: use the ``pages`` property of the returned iterator
377+
instead of manually passing the token.
373378
374379
:type client: :class:`google.cloud.dns.client.Client`
375380
:param client:

‎firestore/google/cloud/firestore_v1beta1/document.py‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -459,7 +459,9 @@ def collections(self, page_size=None):
459459
"""List subcollections of the current document.
460460
461461
Args:
462-
page_size (Optional[int]]): Iterator page size.
462+
page_size (Optional[int]]): The maximum number of collections
463+
in each page of results from this request. Non-positive values
464+
are ignored. Defaults to a sensible value set by the API.
463465
464466
Returns:
465467
Sequence[~.firestore_v1beta1.collection.CollectionReference]:

‎logging/google/cloud/logging/client.py‎

Lines changed: 30 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -191,13 +191,18 @@ def list_entries(
191191
or :data:`~google.cloud.logging.DESCENDING`.
192192
193193
:type page_size: int
194-
:param page_size: maximum number of entries to return, If not passed,
195-
defaults to a value set by the API.
194+
:param page_size:
195+
Optional. The maximum number of entries in each page of results
196+
from this request. Non-positive values are ignored. Defaults
197+
to a sensible value set by the API.
196198
197199
:type page_token: str
198-
:param page_token: opaque marker for the next "page" of entries. If not
199-
passed, the API will return the first page of
200-
entries.
200+
:param page_token:
201+
Optional. If present, return the next batch of entries, using
202+
the value, which must correspond to the ``nextPageToken`` value
203+
returned in the previous response. Deprecated: use the ``pages``
204+
property of the returned iterator instead of manually passing
205+
the token.
201206
202207
:rtype: :class:`~google.api_core.page_iterator.Iterator`
203208
:returns: Iterator of :class:`~google.cloud.logging.entries._BaseEntry`
@@ -244,13 +249,18 @@ def list_sinks(self, page_size=None, page_token=None):
244249
https://cloud.google.com/logging/docs/reference/v2/rest/v2/projects.sinks/list
245250
246251
:type page_size: int
247-
:param page_size: maximum number of sinks to return, If not passed,
248-
defaults to a value set by the API.
252+
:param page_size:
253+
Optional. The maximum number of sinks in each page of results from
254+
this request. Non-positive values are ignored. Defaults to a
255+
sensible value set by the API.
249256
250257
:type page_token: str
251-
:param page_token: opaque marker for the next "page" of sinks. If not
252-
passed, the API will return the first page of
253-
sinks.
258+
:param page_token:
259+
Optional. If present, return the next batch of sinks, using the
260+
value, which must correspond to the ``nextPageToken`` value
261+
returned in the previous response. Deprecated: use the ``pages``
262+
property of the returned iterator instead of manually passing the
263+
token.
254264
255265
:rtype: :class:`~google.api_core.page_iterator.Iterator`
256266
:returns: Iterator of
@@ -288,13 +298,18 @@ def list_metrics(self, page_size=None, page_token=None):
288298
https://cloud.google.com/logging/docs/reference/v2/rest/v2/projects.metrics/list
289299
290300
:type page_size: int
291-
:param page_size: maximum number of metrics to return, If not passed,
292-
defaults to a value set by the API.
301+
:param page_size:
302+
Optional. The maximum number of metrics in each page of results
303+
from this request. Non-positive values are ignored. Defaults to a
304+
sensible value set by the API.
293305
294306
:type page_token: str
295-
:param page_token: opaque marker for the next "page" of metrics. If not
296-
passed, the API will return the first page of
297-
metrics.
307+
:param page_token:
308+
Optional. If present, return the next batch of metrics, using the
309+
value, which must correspond to the ``nextPageToken`` value
310+
returned in the previous response. Deprecated: use the ``pages``
311+
property of the returned iterator instead of manually passing the
312+
token.
298313
299314
:rtype: :class:`~google.api_core.page_iterator.Iterator`
300315
:returns: Iterator of :class:`~google.cloud.logging.metric.Metric`

‎logging/google/cloud/logging/logger.py‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -249,13 +249,18 @@ def list_entries(
249249
or :data:`~google.cloud.logging.DESCENDING`.
250250
251251
:type page_size: int
252-
:param page_size: maximum number of entries to return, If not passed,
253-
defaults to a value set by the API.
252+
:param page_size:
253+
Optional. The maximum number of entries in each page of results
254+
from this request. Non-positive values are ignored. Defaults
255+
to a sensible value set by the API.
254256
255257
:type page_token: str
256-
:param page_token: opaque marker for the next "page" of entries. If not
257-
passed, the API will return the first page of
258-
entries.
258+
:param page_token:
259+
Optional. If present, return the next batch of entries, using
260+
the value, which must correspond to the ``nextPageToken`` value
261+
returned in the previous response. Deprecated: use the ``pages``
262+
property of the returned iterator instead of manually passing
263+
the token.
259264
260265
:rtype: :class:`~google.api_core.page_iterator.Iterator`
261266
:returns: Iterator of log entries accessible to the current logger.

‎monitoring/google/cloud/monitoring_v3/query.py‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -426,9 +426,9 @@ def iter(self, headers_only=False, page_size=None):
426426
427427
:type page_size: int
428428
:param page_size:
429-
(Optional) Positive number specifying the maximum number of points
430-
to return per page. This can be used to control how far the
431-
iterator reads ahead.
429+
(Optional) The maximum number of points in each page of results
430+
from this request. Non-positive values are ignored. Defaults
431+
to a sensible value set by the API.
432432
433433
:raises: :exc:`ValueError` if the query time interval has not been
434434
specified.
@@ -450,7 +450,9 @@ def _build_query_params(self, headers_only=False, page_size=None):
450450
451451
:type page_size: int
452452
:param page_size:
453-
(Optional) A limit on the number of points to return per page.
453+
(Optional) The maximum number of points in each page of results
454+
from this request. Non-positive values are ignored. Defaults
455+
to a sensible value set by the API.
454456
"""
455457
params = {"name": self._project_path, "filter_": self.filter}
456458

‎resource_manager/google/cloud/resource_manager/client.py‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -146,9 +146,10 @@ def list_projects(self, filter_params=None, page_size=None):
146146
details.
147147
148148
:type page_size: int
149-
:param page_size: (Optional) Maximum number of projects to return in a
150-
single page. If not passed, defaults to a value set
151-
by the API.
149+
:param page_size: (Optional) The maximum number of projects in each
150+
page of results from this request. Non-positive
151+
values are ignored. Defaults to a sensible value
152+
set by the API.
152153
153154
:rtype: :class:`~google.api_core.page_iterator.Iterator`
154155
:returns: Iterator of all

‎runtimeconfig/google/cloud/runtimeconfig/config.py‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -222,11 +222,17 @@ def list_variables(self, page_size=None, page_token=None, client=None):
222222
223223
:type page_size: int
224224
:param page_size:
225-
(Optional) Maximum number of variables to return per page.
225+
Optional. The maximum number of variables in each page of results
226+
from this request. Non-positive values are ignored. Defaults
227+
to a sensible value set by the API.
226228
227229
:type page_token: str
228-
:param page_token: opaque marker for the next "page" of variables. If
229-
not passed, will return the first page of variables.
230+
:param page_token:
231+
Optional. If present, return the next batch of variables, using
232+
the value, which must correspond to the ``nextPageToken`` value
233+
returned in the previous response. Deprecated: use the ``pages``
234+
property of the returned iterator instead of manually passing
235+
the token.
230236
231237
:type client: :class:`~google.cloud.runtimeconfig.client.Client`
232238
:param client:

0 commit comments

Comments
 (0)