As of January 1, 2020 this library no longer supports Python 2 on the latest released version. Library versions released prior to that date will continue to be available. For more information please visit
Python 2 support on Google Cloud.
Page Iterators¶Iterators for paging through paged API methods.
These iterators simplify the process of paging through API responses where the request takes a page token and the response is a list of results with a token for the next page. See list pagination in the Google API Style Guide for more details.
API clients that have methods that follow the list pagination pattern can return an Iterator. You can use this iterator to get all of the results across all pages:
>>> results_iterator = client.list_resources() >>> list(results_iterator) # Convert to a list (consumes all values).
Or you can walk your way through items and call off the search early if you find what you’re looking for (resulting in possibly fewer requests):
>>> for resource in results_iterator: ... print(resource.name) ... if not resource.is_valid: ... break
At any point, you may check the number of items consumed by referencing the num_results property of the iterator:
>>> for my_item in results_iterator: ... if results_iterator.num_results >= 10: ... break
When iterating, not every new item will send a request to the server. To iterate based on each page of items (where a page corresponds to a request):
>>> for page in results_iterator.pages:
... print('=' * 20)
... print(' Page number: {:d}'.format(iterator.page_number))
... print(' Items in page: {:d}'.format(page.num_items))
... print(' First item: {!r}'.format(next(page)))
... print('Items remaining: {:d}'.format(page.remaining))
... print('Next page token: {}'.format(iterator.next_page_token))
====================
Page number: 1
Items in page: 1
First item: <MyItemClass at 0x7f1d3cccf690>
Items remaining: 0
Next page token: eav1OzQB0OM8rLdGXOEsyQWSG
====================
Page number: 2
Items in page: 19
First item: <MyItemClass at 0x7f1d3cccffd0>
Items remaining: 18
Next page token: None
Then, for each page you can get all the resources on that page by iterating through it or using list():
>>> list(page)
[
<MyItemClass at 0x7fd64a098ad0>,
<MyItemClass at 0x7fd64a098ed0>,
<MyItemClass at 0x7fd64a098e90>,
]
Bases: google.api_core.page_iterator.Iterator
A generic class for iterating through gRPC list responses.
Note
The class does not take a page_token argument because it can just be specified in the request.
client (google.cloud.client.Client) – The API client. This unused by this class, but kept to satisfy the Iterator interface.
method (Callable[protobuf.Message]) – A bound gRPC method that should take a single message for the request.
request (protobuf.Message) – The request message.
items_field (str) – The field in the response message that has the items for the page.
item_to_value (Callable[GRPCIterator, Any]) – Callable to convert an item from the type in the JSON response into a native object. Will be called with the iterator and a single item.
request_token_field (str) – The field in the request message used to specify the page token.
response_token_field (str) – The field in the response message that has the token for the next page.
max_results (int) – The maximum number of results to fetch.
Iterator of pages in the response.
generator of page instances.
types.GeneratorType[google.api_core.page_iterator.Page]
ValueError – If the iterator has already been started.
Bases: google.api_core.page_iterator.Iterator
A generic class for iterating through HTTP/JSON API list responses.
To make an iterator work, you’ll need to provide a way to convert a JSON item returned from the API into the object of your choice (via item_to_value). You also may need to specify a custom items_key so that a given response (containing a page of results) can be parsed into an iterable page of the actual objects you want.
client (google.cloud.client.Client) – The API client.
api_request (Callable) – The function to use to make API requests. Generally, this will be google.cloud._http.JSONConnection.api_request().
path (str) – The method path to query for the list of items.
item_to_value (Callable[google.api_core.page_iterator.Iterator, Any]) – Callable to convert an item from the type in the JSON response into a native object. Will be called with the iterator and a single item.
items_key (str) – The key in the API response where the list of items can be found.
page_token (str) – A token identifying a page in a result set to start fetching results from.
page_size (int) – The maximum number of results to fetch per page
max_results (int) – The maximum number of results to fetch
extra_params (dict) – Extra query string parameters for the API call.
(Callable[ (page_start) – google.api_core.page_iterator.Iterator, google.api_core.page_iterator.Page, dict]): Callable to provide any special behavior after a new page has been created. Assumed signature takes the Iterator that started the page, the Page that was started and the dictionary containing the page response.
next_token (str) – The name of the field used in the response for page tokens.
Iterator of pages in the response.
generator of page instances.
types.GeneratorType[google.api_core.page_iterator.Page]
ValueError – If the iterator has already been started.
Bases: object
A generic class for iterating through API list responses.
client (google.cloud.client.Client) – The API client.
item_to_value (Callable[google.api_core.page_iterator.Iterator, Any]) – Callable to convert an item from the type in the raw API response into the native object. Will be called with the iterator and a single item.
page_token (str) – A token identifying a page in a result set to start fetching results from.
max_results (int) – The maximum number of results to fetch.
Iterator for each item returned.
A generator of items from the API.
types.GeneratorType[Any]
ValueError – If the iterator has already been started.
The client that created this iterator.
Optional[Any]
Callable to convert an item from the type in the raw API response into the native object. Will be called with the iterator and a single item.
Callable[Iterator, Any]
The maximum number of results to fetch
The token for the next page of results. If this is set before the iterator starts, it effectively offsets the iterator to a specific starting point.
The total number of results fetched so far.
The current page of results.
Iterator of pages in the response.
generator of page instances.
types.GeneratorType[google.api_core.page_iterator.Page]
ValueError – If the iterator has already been started.
Bases: object
Single page of results in an iterator.
parent (google.api_core.page_iterator.Iterator) – The iterator that owns the current page.
items (Sequence[Any]) – An iterable (that also defines __len__) of items from a raw API response.
item_to_value (Callable[google.api_core.page_iterator.Iterator, Any]) – Callable to convert an item from the type in the raw API response into the native object. Will be called with the iterator and a single item.
Optional[google.protobuf.message.Message] (raw_page) – The raw page response.
The Page is an iterator of items.
Get the next value in the page.
Total items in the page.
google.protobuf.message.Message
Remaining items in the page.
AsyncIO iterators for paging through paged API methods.
These iterators simplify the process of paging through API responses where the request takes a page token and the response is a list of results with a token for the next page. See list pagination in the Google API Style Guide for more details.
API clients that have methods that follow the list pagination pattern can return an AsyncIterator:
>>> results_iterator = await client.list_resources()
Or you can walk your way through items and call off the search early if you find what you’re looking for (resulting in possibly fewer requests):
>>> async for resource in results_iterator: ... print(resource.name) ... if not resource.is_valid: ... break
At any point, you may check the number of items consumed by referencing the num_results property of the iterator:
>>> async for my_item in results_iterator: ... if results_iterator.num_results >= 10: ... break
When iterating, not every new item will send a request to the server. To iterate based on each page of items (where a page corresponds to a request):
>>> async for page in results_iterator.pages:
... print('=' * 20)
... print(' Page number: {:d}'.format(iterator.page_number))
... print(' Items in page: {:d}'.format(page.num_items))
... print(' First item: {!r}'.format(next(page)))
... print('Items remaining: {:d}'.format(page.remaining))
... print('Next page token: {}'.format(iterator.next_page_token))
====================
Page number: 1
Items in page: 1
First item: <MyItemClass at 0x7f1d3cccf690>
Items remaining: 0
Next page token: eav1OzQB0OM8rLdGXOEsyQWSG
====================
Page number: 2
Items in page: 19
First item: <MyItemClass at 0x7f1d3cccffd0>
Items remaining: 18
Next page token: None
Bases: google.api_core.page_iterator_async.AsyncIterator
A generic class for iterating through gRPC list responses.
Note
The class does not take a page_token argument because it can just be specified in the request.
client (google.cloud.client.Client) – The API client. This unused by this class, but kept to satisfy the Iterator interface.
method (Callable[protobuf.Message]) – A bound gRPC method that should take a single message for the request.
request (protobuf.Message) – The request message.
items_field (str) – The field in the response message that has the items for the page.
item_to_value (Callable[GRPCIterator, Any]) – Callable to convert an item from the type in the JSON response into a native object. Will be called with the iterator and a single item.
request_token_field (str) – The field in the request message used to specify the page token.
response_token_field (str) – The field in the response message that has the token for the next page.
max_results (int) – The maximum number of results to fetch.
Iterator of pages in the response.
generator of page instances.
types.GeneratorType[google.api_core.page_iterator.Page]
ValueError – If the iterator has already been started.
Bases: abc.ABC
A generic class for iterating through API list responses.
client (google.cloud.client.Client) – The API client.
item_to_value (Callable[google.api_core.page_iterator_async.AsyncIterator, Any]) – Callable to convert an item from the type in the raw API response into the native object. Will be called with the iterator and a single item.
page_token (str) – A token identifying a page in a result set to start fetching results from.
max_results (int) – The maximum number of results to fetch.
Iterator for each item returned.
A generator of items from the API.
types.GeneratorType[Any]
ValueError – If the iterator has already been started.
The client that created this iterator.
Optional[Any]
Callable to convert an item from the type in the raw API response into the native object. Will be called with the iterator and a single item.
Callable[Iterator, Any]
The maximum number of results to fetch.
The token for the next page of results. If this is set before the iterator starts, it effectively offsets the iterator to a specific starting point.
The total number of results fetched so far.
The current page of results.
Iterator of pages in the response.
generator of page instances.
types.GeneratorType[google.api_core.page_iterator.Page]
ValueError – If the iterator has already been started.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4