Skip to content

Commit

Permalink
Docs/fixit: normalize docs for 'page_size' / 'max_results' / 'page_to…
Browse files Browse the repository at this point in the history
…ken' (#6842)
  • Loading branch information
tseaver authored Dec 13, 2018
1 parent f880e4e commit ff05ac3
Show file tree
Hide file tree
Showing 14 changed files with 135 additions and 61 deletions.
5 changes: 3 additions & 2 deletions bigquery/google/cloud/bigquery/client.py
Original file line number Diff line number Diff line change
Expand Up @@ -1674,8 +1674,9 @@ def list_rows(
start_index (int):
(Optional) The zero-based index of the starting row to read.
page_size (int):
(Optional) The maximum number of items to return per page in
the iterator.
Optional. The maximum number of rows in each page of results
from this request. Non-positive values are ignored. Defaults
to a sensible value set by the API.
retry (:class:`google.api_core.retry.Retry`):
(Optional) How to retry the RPC.
Expand Down
4 changes: 3 additions & 1 deletion bigquery/google/cloud/bigquery/table.py
Original file line number Diff line number Diff line change
Expand Up @@ -1240,7 +1240,9 @@ class RowIterator(HTTPIterator):
page_token (str): A token identifying a page in a result set to start
fetching results from.
max_results (int, optional): The maximum number of results to fetch.
page_size (int, optional): The number of items to return per page.
page_size (int, optional): The maximum number of rows in each page
of results from this request. Non-positive values are ignored.
Defaults to a sensible value set by the API.
extra_params (Dict[str, object]):
Extra query string parameters for the API call.
table (Union[ \
Expand Down
8 changes: 5 additions & 3 deletions dns/google/cloud/dns/client.py
Original file line number Diff line number Diff line change
Expand Up @@ -82,9 +82,11 @@ def list_zones(self, max_results=None, page_token=None):
passed, defaults to a value set by the API.
:type page_token: str
:param page_token: opaque marker for the next "page" of zones. If
not passed, the API will return the first page of
zones.
:param page_token: Optional. If present, return the next batch of
zones, using the value, which must correspond to the
``nextPageToken`` value returned in the previous response.
Deprecated: use the ``pages`` property of the returned iterator
instead of manually passing the token.
:rtype: :class:`~google.api_core.page_iterator.Iterator`
:returns: Iterator of :class:`~google.cloud.dns.zone.ManagedZone`
Expand Down
25 changes: 15 additions & 10 deletions dns/google/cloud/dns/zone.py
Original file line number Diff line number Diff line change
Expand Up @@ -325,13 +325,16 @@ def list_resource_record_sets(self, max_results=None, page_token=None, client=No
https://cloud.google.com/dns/api/v1/resourceRecordSets/list
:type max_results: int
:param max_results: maximum number of zones to return, If not
passed, defaults to a value set by the API.
:param max_results: Optional. The maximum number of resource record
sets to return. Defaults to a sensible value
set by the API.
:type page_token: str
:param page_token: opaque marker for the next "page" of zones. If
not passed, the API will return the first page of
zones.
:param page_token: Optional. If present, return the next batch of
resource record sets, using the value, which must correspond to
the ``nextPageToken`` value returned in the previous response.
Deprecated: use the ``pages`` property of the returned iterator
instead of manually passing the token.
:type client: :class:`google.cloud.dns.client.Client`
:param client:
Expand Down Expand Up @@ -363,13 +366,15 @@ def list_changes(self, max_results=None, page_token=None, client=None):
https://cloud.google.com/dns/api/v1/resourceRecordSets/list
:type max_results: int
:param max_results: maximum number of zones to return, If not
passed, defaults to a value set by the API.
:param max_results: Optional. The maximum number of change sets
to return. Defaults to a sensible value set by the API.
:type page_token: str
:param page_token: opaque marker for the next "page" of zones. If
not passed, the API will return the first page of
zones.
:param page_token: Optional. If present, return the next batch of
change sets, using the value, which must correspond to the
``nextPageToken`` value returned in the previous response.
Deprecated: use the ``pages`` property of the returned iterator
instead of manually passing the token.
:type client: :class:`google.cloud.dns.client.Client`
:param client:
Expand Down
4 changes: 3 additions & 1 deletion firestore/google/cloud/firestore_v1beta1/document.py
Original file line number Diff line number Diff line change
Expand Up @@ -459,7 +459,9 @@ def collections(self, page_size=None):
"""List subcollections of the current document.
Args:
page_size (Optional[int]]): Iterator page size.
page_size (Optional[int]]): The maximum number of collections
in each page of results from this request. Non-positive values
are ignored. Defaults to a sensible value set by the API.
Returns:
Sequence[~.firestore_v1beta1.collection.CollectionReference]:
Expand Down
45 changes: 30 additions & 15 deletions logging/google/cloud/logging/client.py
Original file line number Diff line number Diff line change
Expand Up @@ -191,13 +191,18 @@ def list_entries(
or :data:`~google.cloud.logging.DESCENDING`.
:type page_size: int
:param page_size: maximum number of entries to return, If not passed,
defaults to a value set by the API.
:param page_size:
Optional. The maximum number of entries in each page of results
from this request. Non-positive values are ignored. Defaults
to a sensible value set by the API.
:type page_token: str
:param page_token: opaque marker for the next "page" of entries. If not
passed, the API will return the first page of
entries.
:param page_token:
Optional. If present, return the next batch of entries, using
the value, which must correspond to the ``nextPageToken`` value
returned in the previous response. Deprecated: use the ``pages``
property of the returned iterator instead of manually passing
the token.
:rtype: :class:`~google.api_core.page_iterator.Iterator`
:returns: Iterator of :class:`~google.cloud.logging.entries._BaseEntry`
Expand Down Expand Up @@ -244,13 +249,18 @@ def list_sinks(self, page_size=None, page_token=None):
https://cloud.google.com/logging/docs/reference/v2/rest/v2/projects.sinks/list
:type page_size: int
:param page_size: maximum number of sinks to return, If not passed,
defaults to a value set by the API.
:param page_size:
Optional. 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.
:type page_token: str
:param page_token: opaque marker for the next "page" of sinks. If not
passed, the API will return the first page of
sinks.
:param page_token:
Optional. 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 of the returned iterator instead of manually passing the
token.
:rtype: :class:`~google.api_core.page_iterator.Iterator`
:returns: Iterator of
Expand Down Expand Up @@ -288,13 +298,18 @@ def list_metrics(self, page_size=None, page_token=None):
https://cloud.google.com/logging/docs/reference/v2/rest/v2/projects.metrics/list
:type page_size: int
:param page_size: maximum number of metrics to return, If not passed,
defaults to a value set by the API.
:param page_size:
Optional. The maximum number of metrics in each page of results
from this request. Non-positive values are ignored. Defaults to a
sensible value set by the API.
:type page_token: str
:param page_token: opaque marker for the next "page" of metrics. If not
passed, the API will return the first page of
metrics.
:param page_token:
Optional. If present, return the next batch of metrics, using the
value, which must correspond to the ``nextPageToken`` value
returned in the previous response. Deprecated: use the ``pages``
property of the returned iterator instead of manually passing the
token.
:rtype: :class:`~google.api_core.page_iterator.Iterator`
:returns: Iterator of :class:`~google.cloud.logging.metric.Metric`
Expand Down
15 changes: 10 additions & 5 deletions logging/google/cloud/logging/logger.py
Original file line number Diff line number Diff line change
Expand Up @@ -249,13 +249,18 @@ def list_entries(
or :data:`~google.cloud.logging.DESCENDING`.
:type page_size: int
:param page_size: maximum number of entries to return, If not passed,
defaults to a value set by the API.
:param page_size:
Optional. The maximum number of entries in each page of results
from this request. Non-positive values are ignored. Defaults
to a sensible value set by the API.
:type page_token: str
:param page_token: opaque marker for the next "page" of entries. If not
passed, the API will return the first page of
entries.
:param page_token:
Optional. If present, return the next batch of entries, using
the value, which must correspond to the ``nextPageToken`` value
returned in the previous response. Deprecated: use the ``pages``
property of the returned iterator instead of manually passing
the token.
:rtype: :class:`~google.api_core.page_iterator.Iterator`
:returns: Iterator of log entries accessible to the current logger.
Expand Down
10 changes: 6 additions & 4 deletions monitoring/google/cloud/monitoring_v3/query.py
Original file line number Diff line number Diff line change
Expand Up @@ -426,9 +426,9 @@ def iter(self, headers_only=False, page_size=None):
:type page_size: int
:param page_size:
(Optional) Positive number specifying the maximum number of points
to return per page. This can be used to control how far the
iterator reads ahead.
(Optional) The maximum number of points in each page of results
from this request. Non-positive values are ignored. Defaults
to a sensible value set by the API.
:raises: :exc:`ValueError` if the query time interval has not been
specified.
Expand All @@ -450,7 +450,9 @@ def _build_query_params(self, headers_only=False, page_size=None):
:type page_size: int
:param page_size:
(Optional) A limit on the number of points to return per page.
(Optional) The maximum number of points in each page of results
from this request. Non-positive values are ignored. Defaults
to a sensible value set by the API.
"""
params = {"name": self._project_path, "filter_": self.filter}

Expand Down
7 changes: 4 additions & 3 deletions resource_manager/google/cloud/resource_manager/client.py
Original file line number Diff line number Diff line change
Expand Up @@ -146,9 +146,10 @@ def list_projects(self, filter_params=None, page_size=None):
details.
:type page_size: int
:param page_size: (Optional) Maximum number of projects to return in a
single page. If not passed, defaults to a value set
by the API.
:param page_size: (Optional) The maximum number of projects in each
page of results from this request. Non-positive
values are ignored. Defaults to a sensible value
set by the API.
:rtype: :class:`~google.api_core.page_iterator.Iterator`
:returns: Iterator of all
Expand Down
12 changes: 9 additions & 3 deletions runtimeconfig/google/cloud/runtimeconfig/config.py
Original file line number Diff line number Diff line change
Expand Up @@ -222,11 +222,17 @@ def list_variables(self, page_size=None, page_token=None, client=None):
:type page_size: int
:param page_size:
(Optional) Maximum number of variables to return per page.
Optional. The maximum number of variables in each page of results
from this request. Non-positive values are ignored. Defaults
to a sensible value set by the API.
:type page_token: str
:param page_token: opaque marker for the next "page" of variables. If
not passed, will return the first page of variables.
:param page_token:
Optional. If present, return the next batch of variables, using
the value, which must correspond to the ``nextPageToken`` value
returned in the previous response. Deprecated: use the ``pages``
property of the returned iterator instead of manually passing
the token.
:type client: :class:`~google.cloud.runtimeconfig.client.Client`
:param client:
Expand Down
24 changes: 20 additions & 4 deletions spanner/google/cloud/spanner_v1/client.py
Original file line number Diff line number Diff line change
Expand Up @@ -191,10 +191,18 @@ def list_instance_configs(self, page_size=None, page_token=None):
See `RPC docs`_.
:type page_size: int
:param page_size: (Optional) Maximum number of results to return.
:param page_size:
Optional. The maximum number of configs in each page of results
from this request. Non-positive values are ignored. Defaults
to a sensible value set by the API.
:type page_token: str
:param page_token: (Optional) Token for fetching next page of results.
:param page_token:
Optional. If present, return the next batch of configs, using
the value, which must correspond to the ``nextPageToken`` value
returned in the previous response. Deprecated: use the ``pages``
property of the returned iterator instead of manually passing
the token.
:rtype: :class:`~google.api_core.page_iterator.Iterator`
:returns:
Expand Down Expand Up @@ -256,10 +264,18 @@ def list_instances(self, filter_="", page_size=None, page_token=None):
the ``ListInstancesRequest`` docs above for examples.
:type page_size: int
:param page_size: (Optional) Maximum number of results to return.
:param page_size:
Optional. The maximum number of instances in each page of results
from this request. Non-positive values are ignored. Defaults
to a sensible value set by the API.
:type page_token: str
:param page_token: (Optional) Token for fetching next page of results.
:param page_token:
Optional. If present, return the next batch of instances, using
the value, which must correspond to the ``nextPageToken`` value
returned in the previous response. Deprecated: use the ``pages``
property of the returned iterator instead of manually passing
the token.
:rtype: :class:`~google.api_core.page_iterator.Iterator`
:returns:
Expand Down
12 changes: 10 additions & 2 deletions spanner/google/cloud/spanner_v1/instance.py
Original file line number Diff line number Diff line change
Expand Up @@ -338,10 +338,18 @@ def list_databases(self, page_size=None, page_token=None):
https://cloud.google.com/spanner/reference/rpc/google.spanner.admin.database.v1#google.spanner.admin.database.v1.DatabaseAdmin.ListDatabases
:type page_size: int
:param page_size: (Optional) Maximum number of results to return.
:param page_size:
Optional. The maximum number of databases in each page of results
from this request. Non-positive values are ignored. Defaults
to a sensible value set by the API.
:type page_token: str
:param page_token: (Optional) Token for fetching next page of results.
:param page_token:
Optional. If present, return the next batch of databases, using
the value, which must correspond to the ``nextPageToken`` value
returned in the previous response. Deprecated: use the ``pages``
property of the returned iterator instead of manually passing
the token.
:rtype: :class:`~google.api._ore.page_iterator.Iterator`
:returns:
Expand Down
14 changes: 10 additions & 4 deletions storage/google/cloud/storage/bucket.py
Original file line number Diff line number Diff line change
Expand Up @@ -623,12 +623,18 @@ def list_blobs(
If :attr:`user_project` is set, bills the API request to that project.
:type max_results: int
:param max_results: (Optional) Maximum number of blobs to return.
:param max_results:
(Optional) The maximum number of blobs in each page of results
from this request. Non-positive values are ignored. Defaults to
a sensible value set by the API.
:type page_token: str
:param page_token: (Optional) Opaque marker for the next "page" of
blobs. If not passed, will return the first page
of blobs.
:param page_token:
(Optional) If present, return the next batch of blobs, using the
value, which must correspond to the ``nextPageToken`` value
returned in the previous response. Deprecated: use the ``pages``
property of the returned iterator instead of manually passing the
token.
:type prefix: str
:param prefix: (Optional) prefix used to filter blobs.
Expand Down
11 changes: 7 additions & 4 deletions storage/google/cloud/storage/client.py
Original file line number Diff line number Diff line change
Expand Up @@ -308,12 +308,15 @@ def list_buckets(
This implements "storage.buckets.list".
:type max_results: int
:param max_results: Optional. Maximum number of buckets to return.
:param max_results: Optional. The maximum number of buckets to return.
:type page_token: str
:param page_token: Optional. Opaque marker for the next "page" of
buckets. If not passed, will return the first page
of buckets.
:param page_token:
Optional. If present, return the next batch of buckets, using the
value, which must correspond to the ``nextPageToken`` value
returned in the previous response. Deprecated: use the ``pages``
property of the returned iterator instead of manually passing the
token.
:type prefix: str
:param prefix: Optional. Filter results to buckets whose names begin
Expand Down

0 comments on commit ff05ac3

Please sign in to comment.