Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1# -*- coding: utf-8 -*-
2# Copyright 2025 Google LLC
3#
4# Licensed under the Apache License, Version 2.0 (the "License");
5# you may not use this file except in compliance with the License.
6# You may obtain a copy of the License at
7#
8# http://www.apache.org/licenses/LICENSE-2.0
9#
10# Unless required by applicable law or agreed to in writing, software
11# distributed under the License is distributed on an "AS IS" BASIS,
12# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13# See the License for the specific language governing permissions and
14# limitations under the License.
15#
16from google.api_core import gapic_v1
17from google.api_core import retry as retries
18from google.api_core import retry_async as retries_async
19from typing import (
20 Any,
21 AsyncIterator,
22 Awaitable,
23 Callable,
24 Sequence,
25 Tuple,
26 Optional,
27 Iterator,
28 Union,
29)
31try:
32 OptionalRetry = Union[retries.Retry, gapic_v1.method._MethodDefault, None]
33 OptionalAsyncRetry = Union[
34 retries_async.AsyncRetry, gapic_v1.method._MethodDefault, None
35 ]
36except AttributeError: # pragma: NO COVER
37 OptionalRetry = Union[retries.Retry, object, None] # type: ignore
38 OptionalAsyncRetry = Union[retries_async.AsyncRetry, object, None] # type: ignore
40from google.cloud.firestore_v1.types import document
41from google.cloud.firestore_v1.types import firestore
42from google.cloud.firestore_v1.types import query
45class ListDocumentsPager:
46 """A pager for iterating through ``list_documents`` requests.
48 This class thinly wraps an initial
49 :class:`google.cloud.firestore_v1.types.ListDocumentsResponse` object, and
50 provides an ``__iter__`` method to iterate through its
51 ``documents`` field.
53 If there are more pages, the ``__iter__`` method will make additional
54 ``ListDocuments`` requests and continue to iterate
55 through the ``documents`` field on the
56 corresponding responses.
58 All the usual :class:`google.cloud.firestore_v1.types.ListDocumentsResponse`
59 attributes are available on the pager. If multiple requests are made, only
60 the most recent response is retained, and thus used for attribute lookup.
61 """
63 def __init__(
64 self,
65 method: Callable[..., firestore.ListDocumentsResponse],
66 request: firestore.ListDocumentsRequest,
67 response: firestore.ListDocumentsResponse,
68 *,
69 retry: OptionalRetry = gapic_v1.method.DEFAULT,
70 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
71 metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
72 ):
73 """Instantiate the pager.
75 Args:
76 method (Callable): The method that was originally called, and
77 which instantiated this pager.
78 request (google.cloud.firestore_v1.types.ListDocumentsRequest):
79 The initial request object.
80 response (google.cloud.firestore_v1.types.ListDocumentsResponse):
81 The initial response object.
82 retry (google.api_core.retry.Retry): Designation of what errors,
83 if any, should be retried.
84 timeout (float): The timeout for this request.
85 metadata (Sequence[Tuple[str, Union[str, bytes]]]): Key/value pairs which should be
86 sent along with the request as metadata. Normally, each value must be of type `str`,
87 but for metadata keys ending with the suffix `-bin`, the corresponding values must
88 be of type `bytes`.
89 """
90 self._method = method
91 self._request = firestore.ListDocumentsRequest(request)
92 self._response = response
93 self._retry = retry
94 self._timeout = timeout
95 self._metadata = metadata
97 def __getattr__(self, name: str) -> Any:
98 return getattr(self._response, name)
100 @property
101 def pages(self) -> Iterator[firestore.ListDocumentsResponse]:
102 yield self._response
103 while self._response.next_page_token:
104 self._request.page_token = self._response.next_page_token
105 self._response = self._method(
106 self._request,
107 retry=self._retry,
108 timeout=self._timeout,
109 metadata=self._metadata,
110 )
111 yield self._response
113 def __iter__(self) -> Iterator[document.Document]:
114 for page in self.pages:
115 yield from page.documents
117 def __repr__(self) -> str:
118 return "{0}<{1!r}>".format(self.__class__.__name__, self._response)
121class ListDocumentsAsyncPager:
122 """A pager for iterating through ``list_documents`` requests.
124 This class thinly wraps an initial
125 :class:`google.cloud.firestore_v1.types.ListDocumentsResponse` object, and
126 provides an ``__aiter__`` method to iterate through its
127 ``documents`` field.
129 If there are more pages, the ``__aiter__`` method will make additional
130 ``ListDocuments`` requests and continue to iterate
131 through the ``documents`` field on the
132 corresponding responses.
134 All the usual :class:`google.cloud.firestore_v1.types.ListDocumentsResponse`
135 attributes are available on the pager. If multiple requests are made, only
136 the most recent response is retained, and thus used for attribute lookup.
137 """
139 def __init__(
140 self,
141 method: Callable[..., Awaitable[firestore.ListDocumentsResponse]],
142 request: firestore.ListDocumentsRequest,
143 response: firestore.ListDocumentsResponse,
144 *,
145 retry: OptionalAsyncRetry = gapic_v1.method.DEFAULT,
146 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
147 metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
148 ):
149 """Instantiates the pager.
151 Args:
152 method (Callable): The method that was originally called, and
153 which instantiated this pager.
154 request (google.cloud.firestore_v1.types.ListDocumentsRequest):
155 The initial request object.
156 response (google.cloud.firestore_v1.types.ListDocumentsResponse):
157 The initial response object.
158 retry (google.api_core.retry.AsyncRetry): Designation of what errors,
159 if any, should be retried.
160 timeout (float): The timeout for this request.
161 metadata (Sequence[Tuple[str, Union[str, bytes]]]): Key/value pairs which should be
162 sent along with the request as metadata. Normally, each value must be of type `str`,
163 but for metadata keys ending with the suffix `-bin`, the corresponding values must
164 be of type `bytes`.
165 """
166 self._method = method
167 self._request = firestore.ListDocumentsRequest(request)
168 self._response = response
169 self._retry = retry
170 self._timeout = timeout
171 self._metadata = metadata
173 def __getattr__(self, name: str) -> Any:
174 return getattr(self._response, name)
176 @property
177 async def pages(self) -> AsyncIterator[firestore.ListDocumentsResponse]:
178 yield self._response
179 while self._response.next_page_token:
180 self._request.page_token = self._response.next_page_token
181 self._response = await self._method(
182 self._request,
183 retry=self._retry,
184 timeout=self._timeout,
185 metadata=self._metadata,
186 )
187 yield self._response
189 def __aiter__(self) -> AsyncIterator[document.Document]:
190 async def async_generator():
191 async for page in self.pages:
192 for response in page.documents:
193 yield response
195 return async_generator()
197 def __repr__(self) -> str:
198 return "{0}<{1!r}>".format(self.__class__.__name__, self._response)
201class PartitionQueryPager:
202 """A pager for iterating through ``partition_query`` requests.
204 This class thinly wraps an initial
205 :class:`google.cloud.firestore_v1.types.PartitionQueryResponse` object, and
206 provides an ``__iter__`` method to iterate through its
207 ``partitions`` field.
209 If there are more pages, the ``__iter__`` method will make additional
210 ``PartitionQuery`` requests and continue to iterate
211 through the ``partitions`` field on the
212 corresponding responses.
214 All the usual :class:`google.cloud.firestore_v1.types.PartitionQueryResponse`
215 attributes are available on the pager. If multiple requests are made, only
216 the most recent response is retained, and thus used for attribute lookup.
217 """
219 def __init__(
220 self,
221 method: Callable[..., firestore.PartitionQueryResponse],
222 request: firestore.PartitionQueryRequest,
223 response: firestore.PartitionQueryResponse,
224 *,
225 retry: OptionalRetry = gapic_v1.method.DEFAULT,
226 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
227 metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
228 ):
229 """Instantiate the pager.
231 Args:
232 method (Callable): The method that was originally called, and
233 which instantiated this pager.
234 request (google.cloud.firestore_v1.types.PartitionQueryRequest):
235 The initial request object.
236 response (google.cloud.firestore_v1.types.PartitionQueryResponse):
237 The initial response object.
238 retry (google.api_core.retry.Retry): Designation of what errors,
239 if any, should be retried.
240 timeout (float): The timeout for this request.
241 metadata (Sequence[Tuple[str, Union[str, bytes]]]): Key/value pairs which should be
242 sent along with the request as metadata. Normally, each value must be of type `str`,
243 but for metadata keys ending with the suffix `-bin`, the corresponding values must
244 be of type `bytes`.
245 """
246 self._method = method
247 self._request = firestore.PartitionQueryRequest(request)
248 self._response = response
249 self._retry = retry
250 self._timeout = timeout
251 self._metadata = metadata
253 def __getattr__(self, name: str) -> Any:
254 return getattr(self._response, name)
256 @property
257 def pages(self) -> Iterator[firestore.PartitionQueryResponse]:
258 yield self._response
259 while self._response.next_page_token:
260 self._request.page_token = self._response.next_page_token
261 self._response = self._method(
262 self._request,
263 retry=self._retry,
264 timeout=self._timeout,
265 metadata=self._metadata,
266 )
267 yield self._response
269 def __iter__(self) -> Iterator[query.Cursor]:
270 for page in self.pages:
271 yield from page.partitions
273 def __repr__(self) -> str:
274 return "{0}<{1!r}>".format(self.__class__.__name__, self._response)
277class PartitionQueryAsyncPager:
278 """A pager for iterating through ``partition_query`` requests.
280 This class thinly wraps an initial
281 :class:`google.cloud.firestore_v1.types.PartitionQueryResponse` object, and
282 provides an ``__aiter__`` method to iterate through its
283 ``partitions`` field.
285 If there are more pages, the ``__aiter__`` method will make additional
286 ``PartitionQuery`` requests and continue to iterate
287 through the ``partitions`` field on the
288 corresponding responses.
290 All the usual :class:`google.cloud.firestore_v1.types.PartitionQueryResponse`
291 attributes are available on the pager. If multiple requests are made, only
292 the most recent response is retained, and thus used for attribute lookup.
293 """
295 def __init__(
296 self,
297 method: Callable[..., Awaitable[firestore.PartitionQueryResponse]],
298 request: firestore.PartitionQueryRequest,
299 response: firestore.PartitionQueryResponse,
300 *,
301 retry: OptionalAsyncRetry = gapic_v1.method.DEFAULT,
302 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
303 metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
304 ):
305 """Instantiates the pager.
307 Args:
308 method (Callable): The method that was originally called, and
309 which instantiated this pager.
310 request (google.cloud.firestore_v1.types.PartitionQueryRequest):
311 The initial request object.
312 response (google.cloud.firestore_v1.types.PartitionQueryResponse):
313 The initial response object.
314 retry (google.api_core.retry.AsyncRetry): Designation of what errors,
315 if any, should be retried.
316 timeout (float): The timeout for this request.
317 metadata (Sequence[Tuple[str, Union[str, bytes]]]): Key/value pairs which should be
318 sent along with the request as metadata. Normally, each value must be of type `str`,
319 but for metadata keys ending with the suffix `-bin`, the corresponding values must
320 be of type `bytes`.
321 """
322 self._method = method
323 self._request = firestore.PartitionQueryRequest(request)
324 self._response = response
325 self._retry = retry
326 self._timeout = timeout
327 self._metadata = metadata
329 def __getattr__(self, name: str) -> Any:
330 return getattr(self._response, name)
332 @property
333 async def pages(self) -> AsyncIterator[firestore.PartitionQueryResponse]:
334 yield self._response
335 while self._response.next_page_token:
336 self._request.page_token = self._response.next_page_token
337 self._response = await self._method(
338 self._request,
339 retry=self._retry,
340 timeout=self._timeout,
341 metadata=self._metadata,
342 )
343 yield self._response
345 def __aiter__(self) -> AsyncIterator[query.Cursor]:
346 async def async_generator():
347 async for page in self.pages:
348 for response in page.partitions:
349 yield response
351 return async_generator()
353 def __repr__(self) -> str:
354 return "{0}<{1!r}>".format(self.__class__.__name__, self._response)
357class ListCollectionIdsPager:
358 """A pager for iterating through ``list_collection_ids`` requests.
360 This class thinly wraps an initial
361 :class:`google.cloud.firestore_v1.types.ListCollectionIdsResponse` object, and
362 provides an ``__iter__`` method to iterate through its
363 ``collection_ids`` field.
365 If there are more pages, the ``__iter__`` method will make additional
366 ``ListCollectionIds`` requests and continue to iterate
367 through the ``collection_ids`` field on the
368 corresponding responses.
370 All the usual :class:`google.cloud.firestore_v1.types.ListCollectionIdsResponse`
371 attributes are available on the pager. If multiple requests are made, only
372 the most recent response is retained, and thus used for attribute lookup.
373 """
375 def __init__(
376 self,
377 method: Callable[..., firestore.ListCollectionIdsResponse],
378 request: firestore.ListCollectionIdsRequest,
379 response: firestore.ListCollectionIdsResponse,
380 *,
381 retry: OptionalRetry = gapic_v1.method.DEFAULT,
382 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
383 metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
384 ):
385 """Instantiate the pager.
387 Args:
388 method (Callable): The method that was originally called, and
389 which instantiated this pager.
390 request (google.cloud.firestore_v1.types.ListCollectionIdsRequest):
391 The initial request object.
392 response (google.cloud.firestore_v1.types.ListCollectionIdsResponse):
393 The initial response object.
394 retry (google.api_core.retry.Retry): Designation of what errors,
395 if any, should be retried.
396 timeout (float): The timeout for this request.
397 metadata (Sequence[Tuple[str, Union[str, bytes]]]): Key/value pairs which should be
398 sent along with the request as metadata. Normally, each value must be of type `str`,
399 but for metadata keys ending with the suffix `-bin`, the corresponding values must
400 be of type `bytes`.
401 """
402 self._method = method
403 self._request = firestore.ListCollectionIdsRequest(request)
404 self._response = response
405 self._retry = retry
406 self._timeout = timeout
407 self._metadata = metadata
409 def __getattr__(self, name: str) -> Any:
410 return getattr(self._response, name)
412 @property
413 def pages(self) -> Iterator[firestore.ListCollectionIdsResponse]:
414 yield self._response
415 while self._response.next_page_token:
416 self._request.page_token = self._response.next_page_token
417 self._response = self._method(
418 self._request,
419 retry=self._retry,
420 timeout=self._timeout,
421 metadata=self._metadata,
422 )
423 yield self._response
425 def __iter__(self) -> Iterator[str]:
426 for page in self.pages:
427 yield from page.collection_ids
429 def __repr__(self) -> str:
430 return "{0}<{1!r}>".format(self.__class__.__name__, self._response)
433class ListCollectionIdsAsyncPager:
434 """A pager for iterating through ``list_collection_ids`` requests.
436 This class thinly wraps an initial
437 :class:`google.cloud.firestore_v1.types.ListCollectionIdsResponse` object, and
438 provides an ``__aiter__`` method to iterate through its
439 ``collection_ids`` field.
441 If there are more pages, the ``__aiter__`` method will make additional
442 ``ListCollectionIds`` requests and continue to iterate
443 through the ``collection_ids`` field on the
444 corresponding responses.
446 All the usual :class:`google.cloud.firestore_v1.types.ListCollectionIdsResponse`
447 attributes are available on the pager. If multiple requests are made, only
448 the most recent response is retained, and thus used for attribute lookup.
449 """
451 def __init__(
452 self,
453 method: Callable[..., Awaitable[firestore.ListCollectionIdsResponse]],
454 request: firestore.ListCollectionIdsRequest,
455 response: firestore.ListCollectionIdsResponse,
456 *,
457 retry: OptionalAsyncRetry = gapic_v1.method.DEFAULT,
458 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
459 metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
460 ):
461 """Instantiates the pager.
463 Args:
464 method (Callable): The method that was originally called, and
465 which instantiated this pager.
466 request (google.cloud.firestore_v1.types.ListCollectionIdsRequest):
467 The initial request object.
468 response (google.cloud.firestore_v1.types.ListCollectionIdsResponse):
469 The initial response object.
470 retry (google.api_core.retry.AsyncRetry): Designation of what errors,
471 if any, should be retried.
472 timeout (float): The timeout for this request.
473 metadata (Sequence[Tuple[str, Union[str, bytes]]]): Key/value pairs which should be
474 sent along with the request as metadata. Normally, each value must be of type `str`,
475 but for metadata keys ending with the suffix `-bin`, the corresponding values must
476 be of type `bytes`.
477 """
478 self._method = method
479 self._request = firestore.ListCollectionIdsRequest(request)
480 self._response = response
481 self._retry = retry
482 self._timeout = timeout
483 self._metadata = metadata
485 def __getattr__(self, name: str) -> Any:
486 return getattr(self._response, name)
488 @property
489 async def pages(self) -> AsyncIterator[firestore.ListCollectionIdsResponse]:
490 yield self._response
491 while self._response.next_page_token:
492 self._request.page_token = self._response.next_page_token
493 self._response = await self._method(
494 self._request,
495 retry=self._retry,
496 timeout=self._timeout,
497 metadata=self._metadata,
498 )
499 yield self._response
501 def __aiter__(self) -> AsyncIterator[str]:
502 async def async_generator():
503 async for page in self.pages:
504 for response in page.collection_ids:
505 yield response
507 return async_generator()
509 def __repr__(self) -> str:
510 return "{0}<{1!r}>".format(self.__class__.__name__, self._response)